LDP
/
LDP
mirror of https://github.com/tLDP/LDP
0
1
Fork 0
Code Releases Activity
LDP/LDP/howto/docbook/PHP-Nuke-HOWTO/PHP-Nuke-HOWTO.sgml

14463 lines
1.5 MiB
Raw Blame History

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
[ <!entity index SYSTEM "index.sgml">
<!entity bibliography SYSTEM "bibliography.sgml">
<!entity appendix SYSTEM "appendix.sgml">
<!ENTITY % output.print.png "INCLUDE">
<!ENTITY % output.print.pdf "IGNORE">
<!ENTITY % output.print.eps "INCLUDE">
<!ENTITY % output.print.bmp "IGNORE">
<!ENTITY graph1001 "logo1">
<!ENTITY graph1002 "logo2">
<!ENTITY graph1003 "php-nuke">
<!ENTITY graph1004 "ws-ftp-general">
<!ENTITY graph1005 "ws-ftp-local-remote">
<!ENTITY graph1006 "snapshot12">
<!ENTITY graph1007 "ws-ftp-chmod-1">
<!ENTITY graph1008 "ws-ftp-chmod-2">
<!ENTITY graph1009 "phpmyadmin-start">
<!ENTITY graph1010 "phpmyadmin-select-database">
<!ENTITY graph1011 "phpmyadmin-navigation-bar">
<!ENTITY graph1012 "phpmyadmin-field-functions">
<!ENTITY graph1013 "phpmyadmin-SQL">
<!ENTITY graph1014 "phpmyadmin-database-dump">
<!ENTITY graph1015 "snapshot19">
<!ENTITY graph1016 "phpmyadmin-create-database">
<!ENTITY graph1017 "phpmyadmin-table-structure">
<!ENTITY graph1018 "phpmyadmin-sql-query">
<!ENTITY graph1019 "phpmyadmin-table-data">
<!ENTITY graph1020 "easyphp">
<!ENTITY graph1021 "easyphp2">
<!ENTITY graph1022 "phpinfo-php">
<!ENTITY graph1023 "apache-package">
<!ENTITY graph1024 "mandrake-control-center">
<!ENTITY graph1025 "red-hat-menu-packages">
<!ENTITY graph1026 "red-hat-package-sections">
<!ENTITY graph1027 "red-hat-service-configuration">
<!ENTITY graph1028 "analyze-mysql-connection">
<!ENTITY graph1029 "analyze-warning-mysql">
<!ENTITY graph1030 "modules-admin">
<!ENTITY graph1031 "security-code">
<!ENTITY graph1032 "phpinfo-gd">
<!ENTITY graph1033 "analyze-gd">
<!ENTITY graph1034 "security-code">
<!ENTITY graph1035 "forum">
<!ENTITY graph1036 "forum">
<!ENTITY graph1037 "authors">
<!ENTITY graph1038 "authors">
<!ENTITY graph1039 "phpmyadmin-field-functions">
<!ENTITY graph1040 "forum-gzip-compression">
<!ENTITY graph1041 "modules">
<!ENTITY graph1042 "missing-blocks">
<!ENTITY graph1043 "homepage">
<!ENTITY graph1044 "category">
<!ENTITY graph1045 "downloads-admin">
<!ENTITY graph1046 "private_messages">
<!ENTITY graph1047 "search">
<!ENTITY graph1048 "stats">
<!ENTITY graph1049 "your_account">
<!ENTITY graph1050 "splatt-forum">
<!ENTITY graph1051 "phpbb-forum">
<!ENTITY graph1052 "modules-block">
<!ENTITY graph1053 "waiting-content-block">
<!ENTITY graph1054 "who-is-online">
<!ENTITY graph1055 "languages">
<!ENTITY graph1056 "surveys-block">
<!ENTITY graph1057 "login">
<!ENTITY graph1058 "admin-panel">
<!ENTITY graph1059 "stories">
<!ENTITY graph1060 "article-poll">
<!ENTITY graph1061 "article-poll-block">
<!ENTITY graph1062 "backup">
<!ENTITY graph1063 "banners">
<!ENTITY graph1064 "blocks">
<!ENTITY graph1065 "content">
<!ENTITY graph1066 "downloads">
<!ENTITY graph1067 "authors">
<!ENTITY graph1068 "users">
<!ENTITY graph1069 "encyclopedia">
<!ENTITY graph1070 "ephemerids">
<!ENTITY graph1071 "faq">
<!ENTITY graph1072 "forum">
<!ENTITY graph1073 "referers">
<!ENTITY graph1074 "messages">
<!ENTITY graph1075 "modules">
<!ENTITY graph1076 "modules-admin">
<!ENTITY graph1077 "newsletter">
<!ENTITY graph1078 "optimize">
<!ENTITY graph1079 "preferences">
<!ENTITY graph1080 "reviews">
<!ENTITY graph1081 "sections">
<!ENTITY graph1082 "submissions">
<!ENTITY graph1083 "surveys">
<!ENTITY graph1084 "topics">
<!ENTITY graph1085 "add-topic">
<!ENTITY graph1086 "weblinks">
<!ENTITY graph1087 "logout">
<!ENTITY graph1088 "forum">
<!ENTITY graph1089 "preferences">
<!ENTITY graph1090 "general-site-info">
<!ENTITY graph1091 "footer">
<!ENTITY graph1092 "webmail-options">
<!ENTITY graph1093 "moon-moonsun-sun">
<!ENTITY graph1094 "meteosat">
<!ENTITY graph1095 "my-menu">
<!ENTITY graph1096 "treemenu3">
<!ENTITY graph1097 "treemenu-js">
<!ENTITY graph1098 "sommaire-parametrable">
<!ENTITY graph1099 "random-quotes">
<!ENTITY graph1100 "eventcal">
<!ENTITY graph1101 "eventcal1">
<!ENTITY graph1102 "eventcal2">
<!ENTITY graph1103 "eventcal3">
<!ENTITY graph1104 "eventcal4">
<!ENTITY graph1105 "eventcal5">
<!ENTITY graph1106 "your-account-tweak">
<!ENTITY graph1107 "approve-membership-pending-applications">
<!ENTITY graph1108 "approve-membership-update-approval-message">
<!ENTITY graph1109 "approve-membership-email-management-1">
<!ENTITY graph1110 "approve-membership-email-management-2">
<!ENTITY graph1111 "gallery">
<!ENTITY graph1112 "gallery-related-files">
<!ENTITY graph1113 "ip-tracking">
<!ENTITY graph1114 "ip-tracking-page-view-info">
<!ENTITY graph1115 "camPortal-block">
<!ENTITY graph1116 "camPortal">
<!ENTITY graph1117 "conquercam">
<!ENTITY graph1118 "myheadlines-box">
<!ENTITY graph1119 "myheadlines-subscribe">
<!ENTITY graph1120 "php-nuke-tools-block">
<!ENTITY graph1121 "php-nuke-tools-module-creator">
<!ENTITY graph1122 "upload">
<!ENTITY graph1123 "odp">
<!ENTITY graph1124 "calloways-cart-add-product">
<!ENTITY graph1125 "workboard">
<!ENTITY graph1126 "workboard-admin">
<!ENTITY graph1127 "php-nuke-html-folder">
<!ENTITY graph1128 "extra-info">
<!ENTITY graph1129 "theme-structure-nukenews">
<!ENTITY graph1130 "theme-structure-other">
<!ENTITY graph1131 "top-nav-bar">
<!ENTITY graph1132 "posted-by">
<!ENTITY graph1133 "messages">
<!ENTITY graph1134 "modules-block">
<!ENTITY graph1135 "modules-block">
<!ENTITY graph1136 "treemenu">
<!ENTITY graph1137 "treemenu1">
<!ENTITY graph1138 "treemenu2">
<!ENTITY graph1139 "treemenu3">
<!ENTITY graph1140 "modules">
<!ENTITY graph1141 "faq">
<!ENTITY graph1142 "reviews">
<!ENTITY graph1143 "weblinks">
<!ENTITY graph1144 "your-info-profile-link">
<!ENTITY graph1145 "forum-profile-link">
<!ENTITY graph1146 "your-info-profile">
<!ENTITY graph1147 "forum-profile">
<!ENTITY graph1148 "stories">
<!ENTITY graph1149 "submissions">
<!ENTITY graph1150 "waiting-content-block">
<!ENTITY graph1151 "sections">
<!ENTITY graph1152 "downloads">
<!ENTITY graph1153 "stories">
<!ENTITY graph1154 "admin-panel">
<!ENTITY graph1155 "preferences">
<!ENTITY graph1156 "newsletter">
<!ENTITY graph1157 "blocks">
<!ENTITY graph1158 "snapshot15">
<!ENTITY graph1159 "content">
<!ENTITY graph1160 "hello-world-javascript">
<!ENTITY graph1161 "help-center-live-main">
<!ENTITY graph1162 "help-center-live-block-offline">
<!ENTITY graph1163 "help-center-live-block-trouble-ticket">
<!ENTITY graph1164 "help-center-live-block-online">
<!ENTITY graph1165 "help-center-live-block-request-monitor">
<!ENTITY graph1166 "help-center-live-block-user-notify">
<!ENTITY graph1167 "help-center-live-block-user-request">
<!ENTITY graph1168 "paypal1">
<!ENTITY graph1169 "paypal2">
<!ENTITY graph1170 "snapshot16">
<!ENTITY graph1171 "snapshot17">
<!ENTITY graph1172 "iframes">
<!ENTITY graph1173 "logout-module">
<!ENTITY graph1174 "analyze-warning-php">
<!ENTITY graph1175 "analyze-warning-sitekey">
<!ENTITY graph1176 "analyze-warning-webmail">
<!ENTITY graph1177 "optimize">
<!ENTITY graph1178 "optimize-php">
<!ENTITY graph1179 "jpcache">
<!ENTITY graph1180 "pear">
<!ENTITY graph1181 "mmcache">
<!ENTITY graph1182 "mod-rewrite-phpinfo">
<!ENTITY graph1183 "mod-rewrite-control-flow">
<!ENTITY graph1184 "mod-rewrite-back-reference">
<!ENTITY graph1185 "regular-expressions">
<!ENTITY graph1186 "backup">
<!ENTITY graph1187 "backup-db">
<!ENTITY graph1188 "phpmyadmin-sql-query">
<!ENTITY graph1189 "modules">
<!ENTITY graph1190 "weblinks">
<!ENTITY graph1191 "modules">
<!ENTITY graph1192 "modules-admin">
<!ENTITY graph1193 "faq">
<!ENTITY graph1194 "weblinks">
<!ENTITY graph1195 "downloads">
<!ENTITY graph1196 "weblinks">
<!ENTITY graph1197 "ephemerids">
<!ENTITY graph1198 "encyclopedia">
<!ENTITY graph1199 "downloads">
<!ENTITY graph1200 "downloads-add-download">
<!ENTITY graph1201 "downloads-add-download-2">
<!ENTITY graph1202 "downloads-main-categories-maxdate">
<!ENTITY graph1203 "your-info-profile-timezone">
<!ENTITY graph1204 "page-area-model">
<!ENTITY graph1205 "snapshot20">
<!ENTITY graph1206 "snapshot21">
<!ENTITY graph1207 "snapshot22"><!ENTITY lyxarrow "-&gt;">
]>
<book lang="en"><!-- DocBook file was created by LyX 1.2
See http://www.lyx.org/ for more information -->
<bookinfo><title>PHP-Nuke: Management and Programming</title><authorgroup>
<author>
<firstname>Chris</firstname> <surname>Karakas</surname>
<affiliation>
<orgname>www.karakas&mdash;online.de</orgname>
</affiliation>
</author>
<author>
<firstname>Claudio</firstname> <surname>Erba</surname>
<affiliation>
<orgname>www.spaghettibrain.com</orgname>
</affiliation>
</author>
<othercredit role="converter">
<contrib>Conversion from LyX to DocBook SGML, Index, document generation, PHP-Nuke module, see Credits</contrib>
<firstname>Chris</firstname> <surname>Karakas</surname>
<affiliation>
<orgname>www.karakas&mdash;online.de</orgname>
</affiliation>
</othercredit>
<othercredit role="translator">
<contrib>Translation from italian (v.1.0) and translation project coordination, see Credits</contrib>
<firstname>Andre</firstname> <surname>Purfield</surname>
<affiliation>
<orgname>oss.cs&mdash;consultants.com</orgname>
</affiliation>
</othercredit>
<othercredit role="translator">
<contrib>Translation from italian (v.1.0), see Credits</contrib>
<firstname>Fortunato</firstname> <surname>Matarazzo</surname>
</othercredit>
<othercredit role="translator">
<contrib>Translation from italian (v.1.0), see Credits</contrib>
<firstname>Chris</firstname> <surname>Karakas</surname>
<affiliation>
<orgname>www.karakas&mdash;online.de</orgname>
</affiliation>
</othercredit>
</authorgroup>
<keywordset>
<keyword>PHP-Nuke</keyword>
<keyword>programming</keyword>
<keyword>management</keyword>
<keyword>tutorial</keyword>
<keyword>PHP</keyword>
<keyword>MySQL</keyword>
<keyword>Linux</keyword>
<keyword>structure</keyword>
<keyword>news</keyword>
<keyword>content management system</keyword>
<keyword>CMS</keyword>
<keyword>UNIX</keyword>
<keyword>nuke</keyword>
<keyword>modules</keyword>
<keyword>blocks</keyword>
<keyword>topics</keyword>
<keyword>themes</keyword>
<keyword>architecture</keyword>
<keyword>howto</keyword>
<keyword>guide</keyword>
<keyword>content</keyword>
<keyword>download</keyword>
<keyword>book</keyword>
<keyword>installation</keyword>
<keyword>permissions</keyword>
<keyword>error</keyword>
<keyword>sessions</keyword>
<keyword>security</keyword>
<keyword>caching</keyword>
<keyword>optimization</keyword>
<keyword>javascript</keyword>
<keyword>googletap</keyword>
<keyword>backup</keyword>
<keyword>flash</keyword>
</keywordset>
<abstract><para>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1001;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1001;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1001;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1001;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Figure</phrase>
</textobject>
</mediaobject></para><para>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1002;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1002;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1002;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1002;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Figure</phrase>
</textobject>
</mediaobject></para><para>There has always been the necessity to have a definitive guide on <application>PHP-Nuke</application>. This guide describes the installation and structure of <application>PHP-Nuke</application> and the details of customizing the front end to suit the users' needs. The architecture of PHP-Nuke, with its modules, blocks, topics and themes is presented in detail, as well as the interplay of <acronym>PHP</acronym> and MySQL for the creation of a mighty content management system (CMS).It also delves into more advanced issues, like the programming of <application>PHP-Nuke</application> blocks and modules, security, acceleration, and optimization. Day-to-day operations and miscellaneous topics are also covered.</para></abstract><REVHISTORY>
<REVISION>
<REVNUMBER>2.1
</REVNUMBER>
<DATE>04.08.2005
</DATE>
<AUTHORINITIALS>CK
</AUTHORINITIALS>
<REVREMARK>
Security bugfix and maintainance release. Fixed typos, made some improvements, closed a security hole in the section on How to include a HTML file and its links (thanks to waraxe for this, see http://www.waraxe.us), closed the same security hole in the PHP-Nuke module version of this document, added code for keycaps, applications, acronyms and product names in the CSS and some enhancements in jadetex.cfg.
</REVREMARK>
</REVISION>
<REVISION>
<REVNUMBER>2.0
</REVNUMBER>
<DATE>16.02.2004
</DATE>
<AUTHORINITIALS>CK
</AUTHORINITIALS>
<REVREMARK>
Added more than 400 pages of additional material. See Credits section for the exact details.
</REVREMARK>
</REVISION>
<REVISION>
<REVNUMBER>1.2.1
</REVNUMBER>
<DATE>22.08.2003
</DATE>
<AUTHORINITIALS>CK
</AUTHORINITIALS>
<REVREMARK>Now available as PHP-Nuke module too. Link to the module source in the Formats section. Smaller logo.
</REVREMARK>
</REVISION>
<REVISION>
<REVNUMBER>1.2
</REVNUMBER>
<DATE>29.05.2003
</DATE>
<AUTHORINITIALS>CK
</AUTHORINITIALS>
<REVREMARK>New logo, CSS stylesheet, HTML validation, footer icons. Incorporated LDP reviewer's comments. Created Aknowledgements and Availability of sources sections.
</REVREMARK>
</REVISION>
<REVISION>
<REVNUMBER>1.1
</REVNUMBER>
<DATE>13.02.2003
</DATE>
<AUTHORINITIALS>AP
</AUTHORINITIALS>
<REVREMARK>Cleaned up the wording and a few typos.
</REVREMARK>
</REVISION>
<REVISION>
<REVNUMBER>1.0
</REVNUMBER>
<DATE>09.01.2003
</DATE>
<AUTHORINITIALS>CK
</AUTHORINITIALS>
<REVREMARK>First complete version.
</REVREMARK>
</REVISION>
</REVHISTORY>
</bookinfo>
<chapter id="terms"><title>Terms of distribution</title><sect1 id="disclaimer"><title>Disclaimer</title><para>No liability for the contents of this documents can be accepted. Use the concepts,<indexterm><primary>concepts</primary></indexterm> examples and other content at your own risk. As this is a new edition of this document, there may be errors and inaccuracies, that may of course be damaging to your system.<indexterm><primary>system</primary></indexterm> Proceed with caution, and although this is highly unlikely, the author does not take any responsibility for that.</para><para>All copyrights are held by their respective owners, unless specifically noted otherwise. Use of a term in this document should not be regarded as affecting the validity of any trademark or service mark.</para><para>Naming of particular products or brands should not be seen as endorsements.</para></sect1>
<sect1 id="formats"><title>Formats</title><tip>
<title>
Include the <application>PHP-Nuke</application> HOWTO as a module in your <application>PHP-Nuke</application> site!
</title>
<para>
You can include the <ulink url="http://www.karakas-online.de/EN-Book/">PHP-Nuke HOWTO</ulink> in your <application>PHP-Nuke</application> site as a module using either the method of <xref linkend="include-HTML-file-and-links-in-module"> or the method of <xref linkend="include-HTML-file-and-links-in-module-iframe">!
</para>
<para>
To use the method of <xref linkend="include-HTML-file-and-links-in-module">, download the <ulink url="http://www.karakas-online.de/EN-Book/EN-Book-Nuke.tar.gz">PHP-Nuke module version of the <application>PHP-Nuke</application> HOWTO</ulink> and install it according to the instruction in the accompanying INSTALL file.
</para>
<para>
To use the method of <xref linkend="include-HTML-file-and-links-in-module-iframe">, just make a module with an index.php file exactly as in the example shown there. It will show the starting page of the PHP-HOWTO in an iframe (<xref linkend="fig-iframes">) and you will be able to navigate its pages without installing anything locally. You have Chris' explicit permission for this.
<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_smile.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_smile.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_smile.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_smile.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject>
</para>
</tip>
<para>This document is available in the following formats:<indexterm><primary>formats</primary></indexterm></para><itemizedlist><listitem><para><ulink url="./book1.html">HTML (HyperText Markup Language)</ulink>, many HTML files (one for every section), for viewing with <ulink url="http://www.anybrowser.org/campaign/">any browser</ulink></para></listitem><listitem><para><ulink url="./EN-Book.html">HTML (HyperText Markup Language)</ulink>, one big HTML file</para></listitem><listitem><para><ulink url="http://www.karakas-online.de/EN-Book/EN-Book-Nuke.tar.gz">PHP-Nuke Module</ulink></para></listitem><listitem><para><ulink url="./EN-Book.txt">TXT (ASCII Text)</ulink></para></listitem><listitem><para><ulink url="./EN-Book.rtf">RTF (Rich Text Format)</ulink></para></listitem><listitem><para><ulink url="./EN-Book.pdf">PDF (Portable Document Format)</ulink></para></listitem><listitem><para><ulink url="./EN-Book.ps.gz">PS.GZ (Compressed Postscript)</ulink></para></listitem><listitem><para><ulink url="./EN-Book.sgml">SGML (Standard Generalized Markup Language)</ulink>, (with the <ulink url="appendix.sgml">Appendix</ulink>)</para></listitem><listitem><para><ulink url="./EN-Book.lyx">LYX (LaTeX frontend LyX)</ulink>, (with the <ulink url="appendix.lyx">Appendix</ulink>)</para></listitem></itemizedlist><note>
<title>RTF: Page numbers</title>
<para>In order to get correct page numbers in Microsoft Word, type the following after opening the document:</para>
<procedure>
<step>
<para>
<keycombo>
<keycap>CTRL</keycap>
<keycap>END</keycap>
</keycombo>
</para>
</step>
<step>
<para>
<keycombo>
<keycap>CTRL</keycap>
<keycap>A</keycap>
</keycombo>
</para>
</step>
<step>
<para>
<keycombo>
<keycap>F9</keycap>
</keycombo>
</para>
</step>
</procedure>
<para>In Word Viewer 97, you must instead do:</para>
<procedure>
<step>
<para>
<keycombo>
<keycap>CTRL</keycap>
<keycap>END</keycap>
</keycombo>
</para>
</step>
<step>
<para>
<keycombo>
<keycap>ALT</keycap>
</keycombo>
</para>
</step>
<step>
<para>
<keycombo>
<keycap>V</keycap>
</keycombo>
</para>
</step>
<step>
<para>
<keycombo>
<keycap>N</keycap>
</keycombo>
</para>
</step>
<step>
<para>
<keycombo>
<keycap>ALT</keycap>
</keycombo>
</para>
</step>
<step>
<para>
<keycombo>
<keycap>V</keycap>
</keycombo>
</para>
</step>
<step>
<para>
<keycombo>
<keycap>P</keycap>
</keycombo>
</para>
</step>
</procedure>
<para>See <ulink url="http://openjade.sourceforge.net/jadedoc-1.3/rtf.htm">The OpenJade RTF backend</ulink> for more details.</para>
</note>
<important>
<title>IMPORTANT: Downloads for offline reading!</title>
<para>
If you want to download the HTML or RTF formats for offline reading, you will need to download the images as well - PNG for HTML and BMP for RTF, including the callouts! To save you the hassle, I have compiled the following zipped tar archives for offline reading:
</para>
</important>
<itemizedlist><listitem><para><ulink url="http://www.karakas-online.de/EN-Book/EN-Book-html.tar.gz"> TAR.GZ (Compressed TAR Archive), many HTML files with images</ulink></para></listitem><listitem><para><ulink url="http://www.karakas-online.de/EN-Book/EN-Book-onehtml.tar.gz"> TAR.GZ (Compressed TAR Archive), one big HTML file with images</ulink></para></listitem><listitem><para><ulink url="http://www.karakas-online.de/EN-Book/EN-Book-sgml.tar.gz"> TAR.GZ (Compressed TAR Archive), SGML file with images</ulink></para></listitem><listitem><para><ulink url="http://www.karakas-online.de/EN-Book/EN-Book-rtf.tar.gz"> TAR.GZ (Compressed TAR Archive), RTF file with images</ulink></para></listitem></itemizedlist><para>A tarball containing all the above formats,<indexterm><primary>formats</primary></indexterm> including images, is also available:</para><itemizedlist><listitem><para><ulink url="http://www.karakas-online.de/EN-Book/EN-Book.tar.gz"> TAR.GZ (Compressed TAR Archive), All files</ulink></para></listitem></itemizedlist></sect1>
<sect1 id="licence"><title>Licence</title><para>Copyright &copy;<indexterm><primary>copy</primary></indexterm> version 1.0 2002 by <ulink url="http://www.spaghettibrain.com">Claudio Erba</ulink>. Copyright &copy;<indexterm><primary>copy</primary></indexterm> version 2.0 2004 by <ulink url="http://www.karakas-online.de">Chris Karakas</ulink> and <ulink url="http://www.spaghettibrain.com">Claudio Erba</ulink>. Copyright &copy;<indexterm><primary>copy</primary></indexterm> version 2.1 2005 by <ulink url="http://www.karakas-online.de">Chris Karakas</ulink> and <ulink url="http://www.spaghettibrain.com">Claudio Erba</ulink>. Permission is granted to copy,<indexterm><primary>copy</primary></indexterm> distribute and/or modify this document under the terms of the <acronym>GNU</acronym> Free Documentation License,<indexterm><primary>GNU Free Documentation License</primary></indexterm> Version 1.2 or any later version published by the Free Software Foundation;<indexterm><primary>Free Software Foundation</primary></indexterm> with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license can be found in <xref linkend="GNU-Free-Documenation-Licence">, as well as at the <ulink url="http://www.gnu.org/copyleft/fdl.html">GNU Free Documentation License</ulink>.</para><para>Original version 1.0 by <ulink url="http://www.spaghettibrain.com">Claudio Erba</ulink>, webmaster of <ulink url="www.spaghettibrain.com ">spaghettibrain</ulink>, <application>PHP-Nuke</application> italian Mirror, 2002. Second, revised and expanded, version 2.0 2004 by <ulink url="http://www.karakas-online.de">Chris Karakas</ulink> and <ulink url="http://www.spaghettibrain.com">Claudio Erba</ulink> (see <xref linkend="credits"> for details). Corrected 2.1 version 2005 by <ulink url="http://www.karakas-online.de">Chris Karakas</ulink> and <ulink url="http://www.spaghettibrain.com">Claudio Erba</ulink> (see Revision History for details).</para><para>This book, in all its versions (also those modified from third parties in italian, english or whichever other language), for will of the authors, may be reproduced also integrally without violating any law in asmuch as this book is released under the <ulink url="http://www.gnu.org/copyleft/fdl.html">GNU Free Documentation License</ulink>, see <xref linkend="GNU-Free-Documenation-Licence">.</para><para>This book:</para><itemizedlist><listitem><para>May be modified partially or integrally creating manuals for companies, agencies or persons who deal with formatting, changing either the diagram<indexterm><primary>diagram</primary></indexterm> or the contents or the pagination.<indexterm><primary>pagination</primary></indexterm></para></listitem><listitem><para>May be distributed either in its original or in modified form, or either in electronic or in paper format from either field periodicals or not, Internet sites and whichever other medium.</para></listitem><listitem><para>May be used as internal manual by companies, public or private agencies, or universities .</para></listitem><listitem><para>May be used distributed by universities as a hand-out.<indexterm><primary>hand-out</primary></indexterm></para></listitem><listitem><para>May even be resold without having to recognize any type of royalty to the authors on the condition that the purchasers be granted the freedom of making even integral copies, redistribute or resell them.</para></listitem></itemizedlist></sect1>
<sect1 id="availability-of-sources"><title>Availability of sources</title><para>See <xref linkend="formats"> for the modifiable sources of this document. These are the official versions. We (the authors, translators and current maintainers) plan to continue work on this document and add new chapters and enhancements.<indexterm><primary>enhancements</primary></indexterm> If you want to see the version we are currently working on (the &ldquo;bleeding edge&rdquo; version), check <ulink url="http://www.karakas-online.de/EN-Book/">PHP-Nuke: Management and Programming</ulink> from time to time.</para><para>The modifiable sources of Claudio's text (in italian), the images and example files are available in sxi format (OpenOffice Impress)<footnote><para>Openoffice is an office suite completely free which you can download from <ulink url="http://www.openoffice.org">OpenOffice</ulink>.</para></footnote> on <ulink url="http://www.spaghettibrain.com/modules.php?name=Archives&amp;dcategory=PHPNuke+BOOK+-+LIBRO">Downloads Area PHPNuke BOOK - LIBRO on spaghettibrain</ulink>. </para></sect1>
<sect1 id="credits"><title>Credits</title><para>This section documents the efforts that have been invested into this document by its authors, contributors and the community.<indexterm><primary>community</primary></indexterm> We tried hard to give credit where credit is due. However, this does not mean that we used only the sources mentioned explicitly here, in this section. Numerous other sources of information have been used, mainly Forums, such as:</para><itemizedlist><listitem><para><ulink url="http://www.karakas-online.de/forum/phpnuke.html">PHP-Nuke Forum</ulink> of <ulink url="http://www.karakas-online.de">Chris Karakas</ulink>.</para></listitem><listitem><para><ulink url="http://www.spaghettibrain.com">spaghettibrain</ulink> of <ulink url="http://www.spaghettibrain.com">Claudio Erba</ulink>.</para></listitem><listitem><para><ulink url="http://www.nukeforums.com">nukeforums</ulink></para></listitem><listitem><para><ulink url="http://www.nukecops.com">nukecops</ulink></para></listitem></itemizedlist><para>Whenever a source has been used, we have included a link to it. Thus, depending on the context,<indexterm><primary>context</primary></indexterm> you should interpret the links in this document not only as a source of further information on a subject,<indexterm><primary>subject</primary></indexterm> but also as Credit and a &ldquo;Thank you&rdquo; for the idea, the explanation,<indexterm><primary>explanation</primary></indexterm> the discussion or the piece of code it offers. If you feel we have ovelooked something, please feel free to contact us.</para><para>We do not offer a Bibliography,<indexterm><primary>Bibliography</primary></indexterm> as strict academic criteria would require, but this may change in the future, as Chris is working on a <ulink url="http://www.karakas-online.de/mySGML/lyx-bibliography.html">solution to the Bibliography problem</ulink> in the context of <ulink url="http://www.karakas-online.de/mySGML/">LyX and SGML</ulink>. </para><tip>
<title>How to enter hundreds of references in LyX</title>
<para>
If you look in the following <xref linkend="credits-version-1.0">, <xref linkend="credits-versions-1.x"> and especially <xref linkend="credits-version-2.0">, you will notice the exceptionally large number of cross-references that had to be entered. Although a single cross-reference is inserted very easily in LyX (just choose Insert->Cross-reference from the menu, then choose the label of the reference you want), it becomes a real pain if you have to enter hundreds of them, as in our case.
</para>
<para>
Chris' solution to this was to write a script that reads a LyX file and outputs another LyX file that contains references to all labels of the first one. It was easier to copy the references from the file thus created, paste them in <xref linkend="credits-version-2.0">(which deals with version 2.0), then delete references to parts that already existed in version 1.0, than try to insert references to all new parts of version 2.0 by using the menu.
</para>
<para>
You can read about Chris' script in <ulink url="http://www.karakas-online.de/myLinuxTips/mass-insertion-of-cross-references-in-lyx.html">Mass insertion of cross-references in LyX</ulink>.
</para>
</tip>
<sect2 id="credits-version-1.0"><title>Version 1.0</title><para>This book started in version 1.0 as a document in italian language, written by <ulink url="http://www.spaghettibrain.com">Claudio Erba</ulink>. It contained: </para><itemizedlist><listitem><para><xref linkend="terms">, consisting of <xref linkend="disclaimer">, <xref linkend="formats">, <xref linkend="licence">, <xref linkend="availability-of-sources"> and <xref linkend="aknowledgements">. This was Chapter 1 of version 1.0.</para></listitem><listitem><para><xref linkend="introduction">, consisting of <xref linkend="purpose">, <xref linkend="whatis-phpnuke">, <xref linkend="history">, <xref linkend="communities">, and <xref linkend="whyphpnuke">. This was Chapter 2 of version 1.0.</para></listitem><listitem><para><xref linkend="frontend">, consisting of <xref linkend="preinstalled-modules">, a section on AvantGO,<indexterm><primary>AvantGO</primary></indexterm> now removed, <xref linkend="non-installed-modules"> and <xref linkend="preinstalled-blocks">. This was Chapter 3 of version 1.0.</para></listitem><listitem><para><xref linkend="backend">, consisting of <xref linkend="administration-functions"> and <xref linkend="preferences">. This was Chapter 4 of version 1.0.</para></listitem><listitem><para><xref linkend="installation"> consisting of <xref linkend="installation-process">, <xref linkend="download">, <xref linkend="upload">, <xref linkend="permissions">, <xref linkend="phpmyadmin">, <xref linkend="whatis-phpmyadmin">, <xref linkend="install-db">, <xref linkend="config-php-file"> and <xref linkend="resources">. This was Chapter 5 of version 1.0.</para></listitem><listitem><para><xref linkend="architecture">, consisting of <xref linkend="directory-structure">, <xref linkend="main-page-management">, <xref linkend="module-management">, and <xref linkend="admin-management">. This was Chapter 6 of version 1.0.</para></listitem><listitem><para><xref linkend="customization">, consisting of <xref linkend="topic-structure">, <xref linkend="template">, <xref linkend="example-creation-HTML-template"> and <xref linkend="theme-rules">. This was Chapter 7 of version 1.0.</para></listitem><listitem><para><xref linkend="blocks">, consisting of <xref linkend="block-types">, <xref linkend="block-creation">, <xref linkend="block-theory">, <xref linkend="block-practice">. This was Chapter 8 of version 1.0.</para></listitem><listitem><para><xref linkend="creating-modules">, consisting of <xref linkend="creating-modules">, <xref linkend="module-structure">, <xref linkend="module-rules">, <xref linkend="module-public"> and <xref linkend="module-admin">. This was Chapter 9 of version 1.0.</para></listitem><listitem><para><xref linkend="security">, consisting of <xref linkend="permissions2">, <xref linkend="cookies"> and <xref linkend="cookie-hijack">. This was Chapter 10 of version 1.0.</para></listitem><listitem><para><xref linkend="tools">, consisting of <xref linkend="database-tables">, <xref linkend="sql-syntax">, <xref linkend="phpmyadmin2">, <xref linkend="whatis-phpmyadmin">, <xref linkend="install-phpMyAdmin">, <xref linkend="mysql-frontend"> and <xref linkend="foxserv">. This was Chapter 11 of version 1.0.</para></listitem></itemizedlist><para>Version 1.0 came with the following figures:</para><itemizedlist><listitem><para><xref linkend="fig-homepage">, <xref linkend="fig-category">, <xref linkend="fig-downloads-admin">, <xref linkend="fig-private-messages">, <xref linkend="fig-search">, <xref linkend="fig-stats">, <xref linkend="fig-your-account">, <xref linkend="fig-splatt-forum">, <xref linkend="fig-admin-panel">, a screenshot of the News articles that has been removed, <xref linkend="fig-file-structure">, <xref linkend="fig-phpmyadmin-start">, <xref linkend="fig-phpmyadmin-table-structure">, <xref linkend="fig-phpmyadmin-sql-query">, <xref linkend="fig-phpmyadmin-table-data">, <xref linkend="fig-phpmyadmin-database-dump">, <xref linkend="fig-block-example">, <xref linkend="fig-inserting-values">, <xref linkend="fig-example-module">, <xref linkend="fig-forum-topics">, <xref linkend="fig-mysqlfront-connection">, <xref linkend="fig-mysqlfront-export-tables">, <xref linkend="fig-mysqlfront-SQL-query">.</para></listitem></itemizedlist><para>Version 1.0 contained no tables.<indexterm><primary>tables</primary></indexterm></para><para>Andre Purfield of <ulink url="http://www.os-solutions.net">Open Source Solutions</ulink> started the translation project (see the <ulink url="http://www.nukeforums.com/forums/viewtopic.php?topic=11210&amp;forum=23">PHP-Nuke book translation thread</ulink> at nukeforums) and coordinated the work of the translators.<indexterm><primary>translators</primary></indexterm> Fortunato Matarazzo made the transaltion of the version 1.0 Chapters 7, 8 and 9 (see above). <ulink url="http://www.karakas-online.de">Chris Karakas</ulink> translated the rest. Andre imported Fortunato's part into LyX,<indexterm><primary>LyX</primary></indexterm> remade many of the screenshots and also made corrections to the english text of the whole document. Chris imported his part in LyX,<indexterm><primary>LyX</primary></indexterm> formatted the whole document, created the Index and processed the LyX file through his scripts (see <xref linkend="book-behind-book">, for details) to render all the versions and files available from <xref linkend="formats">.</para><para>Chris also made PNG,<indexterm><primary>PNG</primary></indexterm> PDF (encapsulated PDF), EPS (encapsulated Postscript) and BMP versions of all figures. The PDF and EPS versions are included in the PDF and PS versions of the document respectively. The PNG and BMP versions are used by the HTML and RTF versions of the document respectively and are supplied separately in the images folder.</para></sect2>
<sect2 id="credits-versions-1.x"><title>Versions 1.x</title><para>In the 1.x versions, various improvements have been made on the document, as can be seen in the Revision History in the front page:</para><itemizedlist><listitem><para>Version 1.1: Andre Purfield of <ulink url="http://www.os-solutions.net">Open Source Solutions</ulink> cleaned up the wording and a few typos.</para></listitem><listitem><para>Version 1.2: <ulink url="http://www.karakas-online.de">Chris Karakas</ulink> made various improvements:</para><itemizedlist><listitem><para>Added a new logo.<indexterm><primary>logo</primary></indexterm></para></listitem><listitem><para>Added a <ulink url="http://www.karakas-online.de/myLinuxTips/css-for-docbook.html">CSS stylesheet for DocBook</ulink>.</para></listitem><listitem><para>Took care of HTML validation (all HTML pages now are validated as conforming to the HTML 4.01 Transitional standard<footnote><para>all, that is, except those that contain <ulink url="http://www.karakas-online.de/mySGML/lyx-callouts.html">callouts</ulink>, see <ulink url="http://www.karakas-online.de/mySGML/HTML-validation">HTML validation</ulink>.</para></footnote>).</para></listitem><listitem><para>Added footer icons that have the following property: if you click on them, they validate,<indexterm><primary>date</primary></indexterm> depending on the icon, either the HTML code or the CSS code of the page being currently viewed.</para></listitem><listitem><para>Added translation links in the header and footer:<indexterm><primary>footer</primary></indexterm> in the header of each page, you will find links to Google's automatic translation of that page into 5 languages - french,<indexterm><primary>french</primary></indexterm> german, italian, portuguese and spanish. In the footer of each page, on the other hand, you will find links to Alta Vista's automatic &ldquo;Babelfish<indexterm><primary>Babelfish</primary></indexterm>&rdquo; translation of that page into 8 languages: chinese, german, japanese, korean,<indexterm><primary>korean</primary></indexterm> french,<indexterm><primary>french</primary></indexterm> italian, portuguese and spanish.</para></listitem><listitem><para>Incorporated <acronym>LDP</acronym> reviewer's comments.<indexterm><primary>comments</primary></indexterm> </para></listitem><listitem><para>Created <xref linkend="availability-of-sources"> and <xref linkend="aknowledgements">.</para></listitem></itemizedlist></listitem><listitem><para>Version 1.2.1: Chris created the <ulink url="http://www.karakas-online.de/EN-Book/EN-Book-Nuke.tar.gz">PHP-Nuke HOWTO module for PHP-Nuke</ulink>, a module that integrates this HOWTO into your <application>PHP-Nuke</application> site (you could install this module too, tip, tip!). Chris added a link to it in the Formats section (<xref linkend="formats">) and made a smaller logo.<indexterm><primary>logo</primary></indexterm></para></listitem></itemizedlist><para>Due to Chris' efforts, starting from version 1.2 this document is an official HOWTO of the <ulink url="http://www.tldp.org">Linux Documentation Project</ulink>. </para><para>Also, starting from <application>PHP-Nuke</application> version 6.7 FINAL,<indexterm><primary>FINAL</primary></indexterm> this document is included in the docs folder of the standard <application>PHP-Nuke</application> package, as the official <application>PHP-Nuke</application> guide.<indexterm><primary>guide</primary></indexterm></para><para>In all 1.x versions after 1.0, the original italian text has undergone no changes other than those related to translation. But behind the scenes, Chris and Claudio were working fervently for the next version 2.0, which was going to bring dramatic improvements, as you can read in <xref linkend="credits-version-2.0">. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_cool.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_cool.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_cool.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_cool.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject></para>
</sect2>
<sect2 id="credits-version-2.0"><title>Version 2.0</title><para>In version 2.0, <ulink url="http://www.karakas-online.de">Chris Karakas</ulink> added the following Chapters and Sections:<indexterm><primary>Sections</primary></indexterm></para><itemizedlist><listitem><para>In <xref linkend="terms">: <xref linkend="credits">, <xref linkend="credits-version-1.0">, <xref linkend="credits-versions-1.x">, <xref linkend="credits-version-2.0">, <xref linkend="credits-general">, <xref linkend="conventions">, <xref linkend="book-behind-book">, <xref linkend="general-idea">, <xref linkend="book-behind-book-line-of-attack"> and <xref linkend="translate-php-nuke-howto">.</para></listitem><listitem><para>In <xref linkend="introduction">: <xref linkend="PHP-Nuke-forks">, <xref linkend="PHP-Nuke-vs-Post-Nuke">, <xref linkend="PHP-Nuke-vs-XOOPS"> and <xref linkend="XOOPS-vs-Post-Nuke">.</para></listitem><listitem><para>In <xref linkend="installation">: <xref linkend="prerequisites">, <xref linkend="database-creation">, <xref linkend="install-PHP-Nuke-locally">, <xref linkend="XAMPP">, <xref linkend="Apache2Triad">, <xref linkend="more-than-one-php-nuke-sites">, <xref linkend="common-database">, <xref linkend="common-user-base">, <xref linkend="common-installation-problems">, <xref linkend="test-scripts">, <xref linkend="test-php">, <xref linkend="ConnectTest-php">, <xref linkend="analyze-php">, <xref linkend="Warning-mysql-fetch-row-supplied-argument">, <xref linkend="call-to-undefined-function">, <xref linkend="failed-opening-lang-php">, <xref linkend="failed-opening-sql-layer-php">, <xref linkend="sorry-such-file-doesnt-exist">, <xref linkend="warning-setlocale">, <xref linkend="security-code">, <xref linkend="bypass-security-code">, <xref linkend="warning-invalid-argument-supplied">, <xref linkend="Include-path">, <xref linkend="mail-problems">, <xref linkend="login-loop">, <xref linkend="SQL-syntax-error">, <xref linkend="error-update-private-forum-permissions">, <xref linkend="invalid-session-in-forums">, <xref linkend="cannot-create-administrator-account">, <xref linkend="administrator-password-lost">, <xref linkend="garbage-on-page">, <xref linkend="compressed-output-in-forums">, <xref linkend="cannot-add-header-information-in-forums">, <xref linkend="empty-page-in-windows">, <xref linkend="lots-of-Notice-lines">, <xref linkend="descriptive-error-message">, <xref linkend="common-miscellaneous-errors">, <xref linkend="RSS-block-error"> and <xref linkend="MySQL-errno-145">, <xref linkend="modules-disappear">, <xref linkend="forums-cant-create-category-without-name"> and <xref linkend="missing-blocks">.</para></listitem><listitem><para>In <xref linkend="upgrade-php-nuke">: <xref linkend="upgrade-php-nuke-60-65">, <xref linkend="upgrade-instructions-60-without-bbtonuke">, <xref linkend="upgrade-instructions-60-with-bbtonuke">, <xref linkend="upgrade-phpbb-php-nuke">.</para></listitem><listitem><para>In <xref linkend="move-php-nuke">: <xref linkend="transferring-local-installation-to-web"> and <xref linkend="changing-web-hoster">.</para></listitem><listitem><para>The whole <xref linkend="php-nuke-add-ons">: <xref linkend="php-nuke-add-on-themes">, <xref linkend="PHP-Nuke-AutoTheme">, <xref linkend="php-nuke-add-on-blocks">, <xref linkend="PHP-Nuke-Moon-Sun-block">, <xref linkend="PHP-Nuke-Meteosat-block">, <xref linkend="PHP-Nuke-comic-block">, <xref linkend="PHP-Nuke-Menu-Builder">, <xref linkend="PHP-Nuke-Treemenu-with-PHP">, <xref linkend="PHP-Nuke-Treemenu-with-Javascript">, <xref linkend="PHP-Nuke-Google-AdSense-block">, <xref linkend="PHP-Nuke-Random-Quotes-block">, <xref linkend="PHP-Nuke-add-on-modules">, <xref linkend="PHP-Nuke-Daily-Comic-module">, <xref linkend="PHP-Nuke-event-calendar-module">, <xref linkend="NSN-Your-Account-Tweak-module">, <xref linkend="PHP-Nuke-Approve-Membership-module">, <xref linkend="PHP-Nuke-Gallery-module">, <xref linkend="PHP-Nuke-IP-Tracking-module">, <xref linkend="PHP-Nuke-Protector-module">, <xref linkend="PHP-Nuke-WebCam-module">, <xref linkend="PHP-Nuke-My-Headlines-module">, <xref linkend="PHP-Nuke-Tools-module">, <xref linkend="PHP-Nuke-Upload-module">, <xref linkend="Upload-add-on-for-phpBB">, <xref linkend="php-nuke-ODP-module">, <xref linkend="PHP-Nuke-eCommerce-module"> and <xref linkend="PHP-Nuke-WorkBoard-module">.</para></listitem><listitem><para>The whole <xref linkend="session-management">: <xref linkend="how-sessions-work"> and <xref linkend="eliminate-session-checks">.</para></listitem><listitem><para>The whole <xref linkend="editing-PHP-Nuke-files">: <xref linkend="vi">, <xref linkend="Emacs">, <xref linkend="Bluefish">, <xref linkend="UltraEdit">, <xref linkend="WinSyntax">, <xref linkend="HTMLKit">, <xref linkend="Crimson-Editor">, <xref linkend="PHPEd"> (FIXME:<indexterm><primary>FIXME</primary></indexterm> Well, this may not be finished by the time version 2.0 is released, but the will to write it was certainly there! :-) ).</para></listitem><listitem><para>The whole <xref linkend="modifying-PHP-Nuke-database">: <xref linkend="user-extra-information">.</para></listitem><listitem><para>The whole <xref linkend="modifying-PHP-Nuke-texts">: <xref linkend="General-PHP-Nuke-texts">, <xref linkend="PHP-Nuke-module-texts">, and <xref linkend="PHP-Nuke-module-and-block-titles">.</para></listitem><listitem><para>In <xref linkend="customization">: <xref linkend="php-nuke-theme-modifying-header">, <xref linkend="PHP-Nuke-header-create-top-navigation-bar">, <xref linkend="PHP-Nuke-header-insert-SlashOcean-search-box">, <xref linkend="PHP-Nuke-header-change">, <xref linkend="PHP-Nuke-header-change-logo">, <xref linkend="PHP-Nuke-header-change-logo-dynamic">, <xref linkend="PHP-Nuke-header-change-banner-placement">, <xref linkend="PHP-Nuke-header-watermark-background-image">, <xref linkend="tab-body-tags">, <xref linkend="PHP-Nuke-header-display-flash-object">, <xref linkend="hide-left-blocks">, <xref linkend="php-nuke-theme-modifying-body">, <xref linkend="multipage-news-articles">, <xref linkend="change-background-colour">, <xref linkend="php-nuke-theme-modifying-index">, <xref linkend="php-nuke-theme-modifying-footer">, <xref linkend="insert-right-extra-table">, <xref linkend="PHP-Nuke-Copyright-notice">, <xref linkend="php-nuke-theme-modifying-icons">, <xref linkend="change-buggy-php-nuke-theme">, <xref linkend="prevent-users-from-changing-php-nuke-theme">, <xref linkend="change-php-nuke-theme-depending-on-module"> and <xref linkend="change-font-size-php-nuke">.</para></listitem><listitem><para>The whole <xref linkend="modifying-php-nuke-html-header">: <xref linkend="favourites-icon-favicon-ico"> and <xref linkend="prevent-statistics-module-gathering-hits">.</para></listitem><listitem><para>The whole <xref linkend="modifying-mainfile-php">: <xref linkend="allow-special-HTML-tags">, <xref linkend="change-order-of-messages"> and <xref linkend="change-duration-of-public-broadcast-message">.</para></listitem><listitem><para>The whole <xref linkend="modifying-php-nuke-blocks">: <xref linkend="change-buggy-block">, <xref linkend="build-custom-module-blocks">, <xref linkend="fig-modules-block">, <xref linkend="simple-module-block">, <xref linkend="treemenu-block">, <xref linkend="fig-modules-block-2">, <xref linkend="general-idea">, <xref linkend="fig-treemenu">, <xref linkend="fig-treemenu1">, <xref linkend="fig-treemenu2">, <xref linkend="fig-treemenu3">, <xref linkend="what-is-Treemenu">, <xref linkend="build-rss-blocks-with-variable-news-number"> and <xref linkend="scrolling-headlines-in-blocks">.</para></listitem><listitem><para>The whole <xref linkend="modifying-php-nuke-modules">: <xref linkend="modifying-any-PHP-Nuke-module">, <xref linkend="hide-right-blocks">, <xref linkend="change-buggy-module">, <xref linkend="modifying-php-nuke-homepage">, <xref linkend="redirect-users-to-login-page">, <xref linkend="restrict-homepage-to-registered-users">, <xref linkend="modifying-php-nuke-module-faq">, <xref linkend="more-than-127-faq-answers">, <xref linkend="modifying-php-nuke-module-reviews">, <xref linkend="allow-only-registered-users-to-review">, <xref linkend="choose-images-from-dropdown-list">, <xref linkend="modifying-php-nuke-module-web-links">, <xref linkend="display-web-links-in-the-same-window">, <xref linkend="change-number-of-web-links-per-page">, <xref linkend="modifying-php-nuke-moduke-your-account">, <xref linkend="redirect-users-to-homepage">, <xref linkend="redirect-your-info-to-forums-user-profile">, <xref linkend="redirect-users-to-login-and-back">, <xref linkend="disable-registration">, <xref linkend="register-users-immediately">, <xref linkend="approve-users">, <xref linkend="register-users-through-iBill">, <xref linkend="change-maximum-username-length">, <xref linkend="modifying-PHP-Nuke-News-module">, <xref linkend="get-rid-of-br-in-news">, <xref linkend="modifying-PHP-Nuke-submit-news-module">, <xref linkend="bypass-article-approval">, <xref linkend="formatAidHeader-function">, <xref linkend="modifying-PHP-Nuke-sections-module">, <xref linkend="order-articles-in-sections">, <xref linkend="modifying-PHP-Nuke-downloads-module">, <xref linkend="URLs-longer-than-100-characters">, <xref linkend="modifying-PHP-Nuke-stories-archive"> and <xref linkend="order-articles-in-stories-archive">.</para></listitem><listitem><para>The whole <xref linkend="modifying-PHP-Nuke-admin-panel">: <xref linkend="set-arbitrary-stories-number-in-home"> and <xref linkend="allow-HTML-newsletter">.</para></listitem><listitem><para>In <xref linkend="blocks">: <xref linkend="Simple-Content-block">, <xref linkend="how-to-include-files">, <xref linkend="javascript-in-php-nuke-blocks">, <xref linkend="create-hello-world-block">, <xref linkend="create-fade-block">, <xref linkend="create-help-center-live-block">, <xref linkend="tab-Help-Center-Live-setcookie">, <xref linkend="advertisements-in-php-nuke-blocks">, <xref linkend="display-images-php-nuke-blocks">, <xref linkend="display-random-images-php-nuke-blocks">, <xref linkend="paypal-block-for-php-nuke">.</para></listitem><listitem><para>In <xref linkend="creating-modules">: <xref linkend="include-HTML-file-in-module">, <xref linkend="include-HTML-file-and-links-in-module">, <xref linkend="tab-changing-HTML-links">, <xref linkend="tab-changing-HTML-links-2">, <xref linkend="include-HTML-file-and-links-in-module-iframe">, <xref linkend="include-plain-text-file-in-module">, <xref linkend="javascript-in-php-nuke-modules">, <xref linkend="javascript-php">, <xref linkend="javascript-in-php-nuke-modules-complete">, <xref linkend="create-logout-module">, <xref linkend="advertisements-in-php-nuke-modules">, <xref linkend="Google-AdSense-in-news-module">, <xref linkend="Google-AdSense-on-top-of-php-nuke-module">, <xref linkend="HTML-forms-in-module">, </para></listitem><listitem><para>The whole <xref linkend="duplicating-PHP-Nuke-modules">: <xref linkend="duplicating-PHP-Nuke-FAQ-module">.</para></listitem><listitem><para>In <xref linkend="security">: <xref linkend="how-secure-is-php-nuke">, <xref linkend="security-record-software-popularity">, <xref linkend="common-php-nuke-security-vulnerabilities">, <xref linkend="cross-site-scripting-with-php-nuke">, <xref linkend="SQL-injection-with-php-nuke">, <xref linkend="path-disclosure-with-php-nuke">, <xref linkend="cross-site-tracing-with-php-nuke">, <xref linkend="guard-security-vulnerabilities-in-php-nuke">, <xref linkend="security-fixes">, <xref linkend="security-measures">, <xref linkend="security-audit">, <xref linkend="permissions2"> (some changes), <xref linkend="user-cookie-change-duration">, <xref linkend="ban-IP-addresses"> and <xref linkend="hacked-now-what">.</para></listitem><listitem><para>The whole <xref linkend="accelerating-php-nuke">: <xref linkend="caching-php-nuke">, <xref linkend="jpcache">, <xref linkend="jpcache-installation">, <xref linkend="jpcache-configuration">, <xref linkend="jpcache-use">, <xref linkend="cache-lite">, <xref linkend="cache-lite-installation">, <xref linkend="cache-lite-use">, <xref linkend="Turck-MMCache">, <xref linkend="Turck-MMCache-installation">, <xref linkend="Turck-MMCache-installation">, <xref linkend="Turck-MMCache-use"> and <xref linkend="Caching-PHP-Nuke-Conclusion">.</para></listitem><listitem><para>The whole <xref linkend="optimizing-php-nuke">: <xref linkend="search-engines-and-dynamic-URLs">, <xref linkend="search-engines-and-GET-method">, <xref linkend="mod-rewrite">, <xref linkend="mod-rewrite-API-phases">, <xref linkend="mod-rewrite-ruleset-processing">, <xref linkend="mod-rewrite-quoting-special-characters">, <xref linkend="mod-rewrite-regex-backreferences">, <xref linkend="regular-expressions">, <xref linkend="htaccess-file">, <xref linkend="make-php-nuke-search-engine-friendly">, <xref linkend="GoogleTap">, <xref linkend="GoogleTap-requirements">, <xref linkend="GoogleTap-installation">, <xref linkend="GoogleTap-how-it-works">, <xref linkend="tab-urlin-urlout">, <xref linkend="make-PHP-Nuke-hot-link-stealth"> and <xref linkend="make-dynamic-CSS">.</para></listitem><listitem><para>In <xref linkend="solve-common-problems-php-nuke">: <xref linkend="proceed-when-MySQL-slow">, <xref linkend="repair-corrupt-table">, <xref linkend="find-all-registration-links">, <xref linkend="allow-anonymous-web-link-submissions"> and <xref linkend="disable-DEBUG-mode">.</para></listitem><listitem><para>The whole <xref linkend="miscellaneous">: <xref linkend="change-Home-module">, <xref linkend="PHP-Nuke-under-SSL">, <xref linkend="change-PHP-parameters">, <xref linkend="display-html-code-in-faq">, <xref linkend="enter-thousands-of-web-links">, <xref linkend="enter-thousands-of-download-links">, <xref linkend="check-validity-of-web-links">, <xref linkend="enter-thousands-of-ephemerids">, <xref linkend="make-encyclopedia-international">, <xref linkend="find-user-name">, <xref linkend="correct-thousands-of-users-fields">, <xref linkend="date-time">, <xref linkend="find-last-date">, <xref linkend="adjust-server-time">, <xref linkend="Discordian-Calendar">, <xref linkend="deal-with-quotes-in-sitename">, <xref linkend="flash-php-nuke-news"> and <xref linkend="backup-mysql-using-browser">.</para></listitem></itemizedlist><para>In version 2.0, <ulink url="http://www.spaghettibrain.com">Claudio Erba</ulink> added the following Chapters and Sections:<indexterm><primary>Sections</primary></indexterm></para><itemizedlist><listitem><para>In <xref linkend="installation">: <xref linkend="phpmyadmin2">, <xref linkend="phpMyAdmin-navigation-bar-Structure">, <xref linkend="phpMyAdmin-navigation-bar-SQL">, <xref linkend="phpMyAdmin-navigation-bar-Export">, <xref linkend="phpMyAdmin-other-commands">, <xref linkend="install-PHP-Nuke-nukesql">, <xref linkend="easyPHP">, <xref linkend="easyPHP-check-successful-installation">, <xref linkend="Mandrake-Linux-Apache-PHP-MySQL"> and <xref linkend="Red-Hat-Linux-Apache-PHP-MySQL">.</para></listitem><listitem><para>In <xref linkend="upgrade-php-nuke">: The introductory text (<xref linkend="upgrade-php-nuke">) and <xref linkend="PHP-Nuke-upgrade-scripts">.</para></listitem><listitem><para>In <xref linkend="frontend">: A lot of additions and improvements in the whole chapter: <xref linkend="preinstalled-modules">, <xref linkend="non-installed-modules">, <xref linkend="preinstalled-blocks">.</para></listitem><listitem><para>In <xref linkend="backend">: A lot of additions and improvements in the whole chapter: <xref linkend="administration-functions">, <xref linkend="phpBB-Forum-administration"> (which was added in this version) and <xref linkend="preferences">.</para></listitem><listitem><para>In <xref linkend="architecture">: Some changes in <xref linkend="directory-structure"> and <xref linkend="main-page-management">.</para></listitem><listitem><para>In <xref linkend="solve-common-problems-php-nuke">: <xref linkend="restore-PHP-Nuke-from-backup">, <xref linkend="restore-single-table">, <xref linkend="restore-large-backup">, <xref linkend="install-new-modules">, <xref linkend="install-modules-with-no-database-change">, <xref linkend="install-modules-with-database-change">, <xref linkend="install-modules-with-database-files-change"> and <xref linkend="install-patches-correct-errors">.</para></listitem><listitem><para>In <xref linkend="tools">: <xref linkend="HTML-syntax">, <xref linkend="HTML-format-text">, <xref linkend="HTML-create-link">, <xref linkend="HTML-insert-image">, <xref linkend="HTML-create-table">, <xref linkend="CSS-syntax">, <xref linkend="PHP-syntax">, <xref linkend="PHP-variables">, <xref linkend="PHP-functions"> and <xref linkend="PHP-switches">.</para></listitem></itemizedlist><note>
<title>Note</title>
<para>
As you can see, almost all labels of version 1.0 have been preserved in version 2.0 too. More specifically, all labels that give rise to HTML files have been preserved in the LyX file. That's no coincidence: <ulink url="http://www.karakas-online.de/mySGML/cool-labels-dont-change.html">Cool labels don't change!</ulink>
</para>
</note>
<para>Chris translated Claudio's additions from italian and inserted some additions and many cross-references.<indexterm><primary>cross-references</primary></indexterm> On the other hand, some of Claudio's information has found its way in the sections added by Chris.<indexterm><primary>Chris</primary></indexterm> </para><para>We have added the <acronym>GNU</acronym> Free Documentation Licence in the <xref linkend="GNU-Free-Documenation-Licence">.</para><para>The following figures have been added in version 2.0:</para><itemizedlist><listitem><para>Chris added: <xref linkend="fig-ws-ftp-chmod-1">, <xref linkend="fig-ws-ftp-chmod-2">, <xref linkend="fig-analyze-mysql-connection">, <xref linkend="fig-analyze-warning-mysql">, <xref linkend="fig-modules-admin-2">, <xref linkend="fig-security-code">, <xref linkend="fig-phpinfo-gd">, <xref linkend="fig-analyze-gd">, <xref linkend="fig-login-screen">, <xref linkend="fig-forum-3">, <xref linkend="fig-forum-4">, <xref linkend="fig-edit-admins-2">, <xref linkend="fig-edit-admins-3">, <xref linkend="fig-forum-gzip-compression">, <xref linkend="fig-modules-4">, <xref linkend="fig-missing-blocks">, <xref linkend="fig-phpbb-forum">, <xref linkend="fig-modules-block-3">, <xref linkend="fig-waiting-content-block-2">, <xref linkend="fig-languages">, <xref linkend="fig-stories">, <xref linkend="fig-article-poll">, <xref linkend="fig-article-poll-block">, <xref linkend="fig-backup">, <xref linkend="fig-banners">, <xref linkend="fig-blocks">, <xref linkend="fig-content">, <xref linkend="fig-downloads">, <xref linkend="fig-edit-admins">, <xref linkend="fig-edit-users">, <xref linkend="fig-encyclopedia">, <xref linkend="fig-ephemerids">, <xref linkend="fig-faq">, <xref linkend="fig-forum">, <xref linkend="fig-referers">, <xref linkend="fig-messages">, <xref linkend="fig-modules">, <xref linkend="fig-modules-admin">, <xref linkend="fig-newsletter">, <xref linkend="fig-optimize">, <xref linkend="fig-preferences">, <xref linkend="fig-reviews">, <xref linkend="fig-sections">, <xref linkend="fig-submissions">, <xref linkend="fig-surveys">, <xref linkend="fig-topics">, <xref linkend="fig-weblinks">, <xref linkend="fig-logout">, <xref linkend="fig-forum-2">, <xref linkend="fig-preferences-2">, <xref linkend="fig-general-site-info">, <xref linkend="fig-footer">, <xref linkend="fig-webmail-options">, <xref linkend="fig-moon-moonsun-sun">, <xref linkend="fig-meteosat">, <xref linkend="fig-my-menu">, <xref linkend="fig-treemenu3-2">, <xref linkend="fig-treemenu-js">, <xref linkend="fig-sommaire-parametrable">, <xref linkend="fig-Random-Quotes">, <xref linkend="fig-eventcal">, <xref linkend="fig-eventcal1">, <xref linkend="fig-eventcal2">, <xref linkend="fig-eventcal3">, <xref linkend="fig-eventcal4">, <xref linkend="fig-eventcal5">, <xref linkend="fig-your-account-tweak">, <xref linkend="fig-approve-membership-pending-applications">, <xref linkend="fig-approve-membership-approval-message">, <xref linkend="fig-approve-membership-email-management-1">, <xref linkend="fig-approve-membership-email-management-2">, <xref linkend="fig-gallery">, <xref linkend="fig-gallery-related-files">, <xref linkend="fig-ip-tracking">, <xref linkend="fig-ip-tracking-page-view-info">, <xref linkend="fig-camPortal-block">, <xref linkend="fig-camPortal">, <xref linkend="fig-conquercam">, <xref linkend="fig-myheadlines-box">, <xref linkend="fig-myheadlines-subscribe">, <xref linkend="fig-php-nuke-tools-block">, <xref linkend="fig-php-nuke-tools-module-creator">, <xref linkend="fig-upload">, <xref linkend="fig-odp">, <xref linkend="fig-calloways-cart-add-product">, <xref linkend="fig-workboard">, <xref linkend="fig-workboard-admin">, <xref linkend="fig-extra-info">, <xref linkend="fig-top-nav-bar">, <xref linkend="fig-posted-by">, <xref linkend="fig-messages-2">, <xref linkend="fig-modules-block">, <xref linkend="fig-modules-block-2">, <xref linkend="fig-treemenu">, <xref linkend="fig-treemenu1">, <xref linkend="fig-treemenu2">, <xref linkend="fig-treemenu3">, <xref linkend="fig-faq-3">, <xref linkend="fig-reviews-2">, <xref linkend="fig-weblinks-4">, <xref linkend="fig-your-info-profile-link">, <xref linkend="fig-forum-profile-link">, <xref linkend="fig-your-info-profile">, <xref linkend="fig-forum-profile">, <xref linkend="fig-stories-2">, <xref linkend="fig-submissions-2">, <xref linkend="fig-waiting-content-block">, <xref linkend="fig-sections-2">, <xref linkend="fig-downloads-4">, <xref linkend="fig-stories-3">, <xref linkend="fig-admin-panel-2">, <xref linkend="fig-preferences-3">, <xref linkend="fig-newsletter-2">, <xref linkend="fig-blocks-2">, <xref linkend="fig-content-2">, <xref linkend="fig-hello-world-javascript">, <xref linkend="fig-help-center-live-main">, <xref linkend="fig-help-center-live-block-offline">, <xref linkend="fig-help-center-live-block-trouble-ticket">, <xref linkend="fig-help-center-live-block-online">, <xref linkend="fig-help-center-live-block-request-monitor">, <xref linkend="fig-help-center-live-block-user-notify">, <xref linkend="fig-help-center-live-block-user-request">, <xref linkend="fig-paypal1">, <xref linkend="fig-paypal2">, <xref linkend="fig-iframes">, <xref linkend="fig-logout-module">, <xref linkend="fig-analyze-warning-php">, <xref linkend="fig-analyze-warning-sitekey">, <xref linkend="fig-analyze-warning-webmail">, <xref linkend="fig-optimize-2">, <xref linkend="fig-optimize-php">, <xref linkend="fig-jpcache">, <xref linkend="fig-pear">, <xref linkend="fig-mmcache">, <xref linkend="fig-mod-rewrite-phpinfo">, <xref linkend="fig-mod-rewrite-control-flow">, <xref linkend="fig-mod-rewrite-back-reference">, <xref linkend="fig-regular-expressions">, <xref linkend="fig-backup-2">, <xref linkend="fig-phpmyadmin-sql-query-2">, <xref linkend="fig-modules-3">, <xref linkend="fig-weblinks-5">, <xref linkend="fig-modules-2">, <xref linkend="fig-modules-admin-3">, <xref linkend="fig-faq-2">, <xref linkend="fig-weblinks-2">, <xref linkend="fig-downloads-2">, <xref linkend="fig-weblinks-3">, <xref linkend="fig-ephemerids-2">, <xref linkend="fig-encyclopedia-2">, <xref linkend="fig-downloads-3">, <xref linkend="fig-downloads-add-download">, <xref linkend="fig-downloads-add-download-2">, <xref linkend="fig-downloads-main-categories-maxdate">, <xref linkend="fig-your-info-profile-timezone"> and <xref linkend="fig-page-area-model">.</para></listitem><listitem><para>Claudio added: <xref linkend="fig-php-nuke">, <xref linkend="fig-ws-ftp-general">, <xref linkend="fig-ws-ftp-local-remote">, <xref linkend="fig-phpmyadmin-select-database">, <xref linkend="fig-phpmyadmin-navigation-bar">, <xref linkend="fig-phpmyadmin-field-functions">, <xref linkend="fig-phpmyadmin-SQL">, <xref linkend="fig-phpmyadmin-create-database">, <xref linkend="fig-easyphp">, <xref linkend="fig-easyphp2">, <xref linkend="fig-phpinfo-php-Windows">, <xref linkend="fig-apache-package">, <xref linkend="fig-mandrake-control-center">, <xref linkend="fig-red-hat-menu-packages">, <xref linkend="fig-red-hat-package-sections">, <xref linkend="fig-red-hat-service-configuration">, <xref linkend="fig-phpmyadmin-field-functions-2">, <xref linkend="fig-who-is-online">, <xref linkend="fig-surveys-block">, <xref linkend="fig-login">, <xref linkend="fig-add-topic">, <xref linkend="fig-php-nuke-html-folder">, <xref linkend="fig-theme-structure-nukenews">, <xref linkend="fig-theme-structure-other">, <xref linkend="fig-backup-db"> and <xref linkend="fig-modules-admin-3">.</para></listitem></itemizedlist><para>Again, as in version 1.0, Chris made PNG,<indexterm><primary>PNG</primary></indexterm> PDF (encapsulated PDF), EPS (encapsulated Postscript) and BMP versions of <emphasis>all</emphasis> figures to be used in the various formats of the document. </para><para>The following tables have been added in version 2.0:</para><itemizedlist><listitem><para>Chris added: <xref linkend="tab-sections">, <xref linkend="tab-body-tags">, <xref linkend="tab-filter-text">, <xref linkend="tab-check-html">, <xref linkend="tab-Help-Center-Live-setcookie">, <xref linkend="tab-changing-HTML-links">, <xref linkend="tab-changing-HTML-links-2">, <xref linkend="tab-security-vulnerabilities"> and <xref linkend="tab-urlin-urlout">.</para></listitem></itemizedlist><para>Chris wrote all new material of version 2.0 in LyX,<indexterm><primary>LyX</primary></indexterm> formatted the whole document, created the Index (semi-automatically this time, through some of his sed and awk scripts, as described in <ulink url="http://www.karakas-online.de/mySGML/">Document processing with LyX and SGML</ulink>) and processed the LyX file through his scripts (see <xref linkend="book-behind-book">, for details) to render all the versions and files available from <xref linkend="formats">.</para></sect2>
<sect2 id="credits-version-2.1"><title>Version 2.1</title><para>In version 2.1, <ulink url="http://www.karakas-online.de">Chris Karakas</ulink> added the following Chapters and Sections:<indexterm><primary>Sections</primary></indexterm></para><itemizedlist><listitem><para>In <xref linkend="include-HTML-file-in-module">: how to include two files side-by-side in a module.</para></listitem></itemizedlist></sect2>
<sect2 id="credits-general"><title>General</title><para>Some quotes have been taken from the installation files of <ulink url="http://phpnuke.oeg">phpnuke.org</ulink>, as well as from the <ulink url="http://www.mysql.com/documentation/">MySQL manual</ulink>.</para><para>In <xref linkend="regular-expressions"> we use material taken from <ulink url="http://www.tldp.org/LDP/abs/html/x12265.html">A Brief Introduction to Regular Expressions</ulink>.</para><para>The sections on mod_rewrite:<indexterm><primary>rewrite</primary></indexterm> <xref linkend="mod-rewrite-API-phases">, <xref linkend="mod-rewrite-ruleset-processing">, <xref linkend="fig-mod-rewrite-control-flow">, <xref linkend="mod-rewrite-quoting-special-characters"> and <xref linkend="mod-rewrite-regex-backreferences"> have been taken from the <ulink url="http://httpd.apache.org/docs/mod/mod_rewrite.html">Apache Documentation of mod_rewrite</ulink>.</para><para><xref linkend="how-sessions-work"> and part of <xref linkend="eliminate-session-checks"> were taken from a post of Paul S. Owen,<indexterm><primary>Owen</primary></indexterm> Development Team Leader of <ulink url="http://www.phpbb.com">phpBB</ulink>, in <ulink url="http://www.phpbb.com/phpBB/viewtopic.php?t=69493">http://www.phpbb.com/phpBB/viewtopic.php?t=69493</ulink>, as well as in <ulink url="http://www.phpbb.com/kb/article.php?article_id=54">http://www.phpbb.com/kb/article.php?article_id=54</ulink> and are included here with permission.<indexterm><primary>permission</primary></indexterm></para><para><xref linkend="fig-page-area-model"> is taken from W3C's working draft <ulink url="http://www.w3.org/TR/2003/WD-css3-page-20031218/">CSS3 Paged Media Module</ulink>, version of Dec. 18th 2003 and is Copyright &copy;<indexterm><primary>copy</primary></indexterm> 2003 <ulink url="http://www.w3.org">W3C</ulink> (<ulink url="http://www.lcs.mit.edu">MIT</ulink>, <ulink url="http://www.ercim.org">ERCIM</ulink>, <ulink url="http://www.keio.ac.jp">Keio</ulink>), All Rights Reserved. Used with permission according to <ulink url="http://www.w3.org/Consortium/Legal/copyright-documents">W3C document licence</ulink>.</para><para>The examples for admonition in the Conventions Section (<xref linkend="conventions">) were taken from the <ulink url="http://newbiedoc.sourceforge.net/tutorials/docbook-guide/admon-docbook-guide.html.en">Section on admonitions of the DocBook Guide</ulink> of the <ulink url="http://newbiedoc.sourceforge.net">Debian Newbiedoc Project</ulink>.</para><para>The <ulink url="http://www.karakas-online.de/myLinuxTips/css-for-docbook.html">CSS file for DocBook</ulink> that is used in this document , <ulink url="ck-style.css">ck-style.css</ulink>, uses <ulink url="http://www.matterform.com/qbullets/index.php">QBullets</ulink> in links. See <ulink url="http://www.karakas-online.de/mySGML/explain-css.html">Explain CSS</ulink> on how to do this. Thanks to Matterform Media for providing QBullets for free. If you plan to use them on your website,<indexterm><primary>website</primary></indexterm> please observe the <ulink url="http://www.matterform.com/qbullets/usage.html">QBullets usage terms</ulink>. </para><para>The CSS also got important elements from the <ulink url="http://newbiedoc.sourceforge.net/nd-style.css">Newbiedoc CSS file for DocBook</ulink> and Mark Pilgrim's influential <ulink url="http://diveintoaccessibility.org">dive into Accessibility</ulink>. The CSS font size controlling code and its explanation are taken from <ulink url="http://diveintoaccessibility.org/day_26_using_relative_font_sizes.html">Using relative font sizes</ulink>.</para></sect2>
</sect1>
<sect1 id="aknowledgements"><title>Aknowledgements</title><para>Claudio said in the first version (1.x) of this document: </para><para>The following people contribute, directly or indirectly to this project<indexterm><primary>project</primary></indexterm> and their help is hereby kindly aknowledged:</para><itemizedlist><listitem><para><ulink url="http://phpnuke.org">Francisco Burzi</ulink> with all the introductory scripts, found in the files of installation of PHP-Nuke</para></listitem><listitem><para>Vasco Clergy and his daughter Valentina of Lug Rieti for the translations<indexterm><primary>ations</primary></indexterm> of the modules of the handbook</para></listitem><listitem><para>Micaela Bechini,<indexterm><primary>Bechini</primary></indexterm> for the daily translations of <ulink url="http://phpnuke.oeg">phpnuke.org</ulink> from English.<indexterm><primary>English</primary></indexterm></para></listitem><listitem><para>The communities of <ulink url="http://www.splatt.it">Splatt.it</ulink>, <ulink url="http://www.nukeitalia.com">Nukeitalia.com</ulink>, <ulink url="http://www.phpnuke.it">PHPnuke.it</ulink> (and its Mailing List), <ulink url="http://www.postnuke.it">Postnuke.it</ulink>, <ulink url="http://www.envolution.it">envolution.it</ulink>, <ulink url="http://www.xoops.it">xoops.it</ulink> and obviously the 1500 registered users of <ulink url="www.spaghettibrain.com">spaghettibrain</ulink>.</para></listitem><listitem><para>Aemmenet,<indexterm><primary>Aemmenet</primary></indexterm> in the person of Mark Atzori that has granted us free use of the server on which <ulink url="www.spaghettibrain.com">spaghettibrain</ulink> is accommodated.</para></listitem><listitem><para>Roberto Scano of IWA Italy and Patrizia Bertini of <ulink url="http://www.webaccessibile.org">Webaccessibile.org</ulink> for the contributions on usability,<indexterm><primary>usability</primary></indexterm> accessibility and <ulink url="http://www.w3c.org">W3C</ulink> validation.<indexterm><primary>validation</primary></indexterm></para></listitem><listitem><para>Marcello Tansini of <ulink url="http://www.webmasterpoint.org">webmasterpoint.org</ulink> for the support given to the project in terms of visibility.<indexterm><primary>visibility</primary></indexterm></para></listitem><listitem><para>Andrea Birgahi, the best <application>PHP-Nuke</application> Theme Maker of the world for the diagram<indexterm><primary>diagram</primary></indexterm> of <ulink url="www.spaghettibrain.com">spaghettibrain</ulink>, for the logo of the book and a lot more.</para></listitem><listitem><para>My girl Sara for all...</para></listitem><listitem><para>My mother Lella, my sister Cora, my dog Grey and the newly arrived baby<indexterm><primary>baby</primary></indexterm> dog Maya.</para></listitem></itemizedlist><blockquote><para>This book I dedicate it to my Pap<61> Antonio. Hello P<>.<indexterm><primary>P<>.</primary></indexterm></para></blockquote><para>For this second version (2.x), Claudio wishes to thank:</para><itemizedlist><listitem><para>Francisco Burzi, the daddy of PHPNuke,<indexterm><primary>PHPNuke</primary></indexterm> who has chosen this book as the official <application>PHP-Nuke</application> handbook!</para></listitem><listitem><para>The translator and the manager team of the <application>PHP-Nuke</application> HOWTO:<indexterm><primary>HOWTO</primary></indexterm> <ulink url="http://www.karakas-online.de">Chris Karakas</ulink>, <ulink url="http://www.os-solutions.net">Andre Purfield</ulink>, Fortunato Matarrazzo.<indexterm><primary>Matarrazzo</primary></indexterm></para></listitem><listitem><para>Umberto Zaccarini of <ulink url="http://www.wmgitalia.it">WMG Italia</ulink>.</para></listitem><listitem><para>Euro Gala of <ulink url="http://www.eticoweb.it">Eticoweb</ulink>, for the operative and ethical support.</para></listitem><listitem><para>Florence University,<indexterm><primary>University</primary></indexterm> because after reading my book they called me to give a course of CMS at <ulink url="http://www.mastermultimedia.unifi.it">Multimedia Master</ulink>; in particular D.ssa Barbara Iraci, Dott. Diego Mencarelli and Dott. Del Bimbo. Thanks to every master student, too.</para></listitem><listitem><para>My team, the Crew Spaghetti, Andrea Biraghi, Federico Campoli,<indexterm><primary>Campoli</primary></indexterm> Fabio Pirovano, Claudio Demarinis and the casual externals Alex Zollia, Micaela Bechini,<indexterm><primary>Bechini</primary></indexterm> VirtualDarkness.<indexterm><primary>VirtualDarkness</primary></indexterm></para></listitem><listitem><para><ulink url="http://www.ziobudda.net">Michel "Ziobudda" Morelli</ulink>, Fabio Farnesi (<ulink url="http://www.programmiamo.net">programmiamo.net</ulink>), Giovanni Tummarello (<ulink url="http://www.wup.it">wup.it</ulink>), Roberto Scano (IWA Italia), Anna Bruno (<ulink url="http://www.fullpress.it">fullpress.it</ulink>), Alessandro Del Rosso and the De Andreis brothers (<ulink url="http://www.punto-informatico.it">punto-informatico.it</ulink>), for the mediatic space they give me every time.</para></listitem><listitem><para>My mother Lella, my sister Cora, my dogs Maia and Grey.</para></listitem><listitem><para>My Sara for everything.</para></listitem></itemizedlist><para>Chris wishes to thank:</para><itemizedlist><listitem><para><ulink url="http://phpnuke.org">Francisco Burzi</ulink>, for writing <application>PHP-Nuke</application> and publishing it under the <ulink url="http://www.gnu.org/copyleft/gpl.html">GNU General Public License</ulink>.</para></listitem><listitem><para><ulink url="http://www.spaghettibrain.com">Claudio Erba</ulink> for bringing the ball in rolling.</para></listitem><listitem><para><ulink url="http://www.os-solutions.net">Andre Purfield</ulink> for starting this wonderful project in the <ulink url="http://www.nukeforums.com/forums/viewtopic.php?topic=11210&amp;forum=23">PHP-Nuke book translation thread</ulink> at nukeforums.com.<indexterm><primary>nukeforums.com</primary></indexterm></para></listitem><listitem><para>All software developers, whose software is used in the preparation of this document (see <xref linkend="book-behind-book">): </para><itemizedlist><listitem><para><ulink url="http://www.lyx.org">LyX</ulink>,</para></listitem><listitem><para><ulink url="http://www.ctan.org">TeX</ulink>,</para></listitem><listitem><para><ulink url="http://www.latex-project.org">LaTeX</ulink>,</para></listitem><listitem><para><ulink url="http://www.tug.org/applications/pdftex/">pdfTeX</ulink>,</para></listitem><listitem><para><ulink url="http://www.tug.org/applications/hyperref/">hyperref</ulink>,</para></listitem><listitem><para><ulink url="http://openjade.sourceforge.net">openjade</ulink>,</para></listitem><listitem><para><ulink url="http://www.fifi.org/cgi-bin/man2html/usr/share/man/man1/pdfjadetex.1.gz">pdfjadetex</ulink>,</para></listitem><listitem><para><ulink url="http://www.ctan.org/tex-archive/help/Catalogue/entries/thumbpdf.html">thumbpdf</ulink>,</para></listitem><listitem><para><ulink url="http://docbook.sourceforge.net/projects/dsssl/">DocBook DSSSL stylesheets</ulink>,</para></listitem><listitem><para><ulink url="http://docbook.sourceforge.net/release/dsssl/current/doc/indexing.html">collateindex</ulink>,</para></listitem><listitem><para><ulink url="http://www.sgmltools.org">sgmltools</ulink>,</para></listitem><listitem><para><ulink url="http://tidy.sourceforge.net">HTML tidy</ulink>,</para></listitem><listitem><para><ulink url="http://hvdkooij.xs4all.nl/docs-docbook.en.cms">HTML split</ulink>,</para></listitem><listitem><para><ulink url="http://www.gnu.org/software/sed/manual/sed.html">sed</ulink>,</para></listitem><listitem><para><ulink url="runsed">runsed</ulink>,</para></listitem><listitem><para><ulink url="http://www.gnu.org/software/gawk/manual/gawk.html">awk</ulink>,</para></listitem><listitem><para><ulink url="http://www.radicaleye.com/dvips.html">dvips</ulink>,</para></listitem><listitem><para>and all the standard software used in a <ulink url="http://www.gnu.org">GNU/Linux</ulink> system.<indexterm><primary>system</primary></indexterm></para></listitem></itemizedlist></listitem><listitem><para><ulink url="http://www.nukeforums.com">nukeforums</ulink> for providing a Forum for the initial stages of this project (see the <ulink url="http://www.nukeforums.com/forums/viewtopic.php?topic=11210&amp;forum=23">PHP-Nuke book translation thread</ulink>), as well as all its numerous readers for their questions and answers - who have influenced many solutions presented in this document. Special thanks go to its most active members<indexterm><primary>members</primary></indexterm></para><itemizedlist><listitem><para><ulink url="http://www.humpa.com">Humpa</ulink>, </para></listitem><listitem><para><ulink url="http://www.nukeresources.com">Chatserv</ulink>, </para></listitem><listitem><para><ulink url="http://www.sengers-au.com">Chris-au</ulink>, </para></listitem></itemizedlist><para>for all the useful advice. I've learned a lot from you!</para></listitem><listitem><para>Paul S. Owen for his contribution in <xref linkend="session-management"> on session management.<indexterm><primary>management</primary></indexterm></para></listitem><listitem><para>Mark Pilgrim for writing <ulink url="http://diveintoaccessibility.org/table_of_contents.html">Dive into Accessibility</ulink> and publishing it under the <ulink url="http://www.gnu.org/copyleft/fdl.html">GNU Free Documentation License</ulink>.</para></listitem><listitem><para>All authors of documentation used in various places (see <xref linkend="credits">):</para><itemizedlist><listitem><para><ulink url="http://phpnuke.oeg">PHP-Nuke</ulink>,</para></listitem><listitem><para><ulink url="http://www.php.net/manual/en/">PHP manual</ulink>,</para></listitem><listitem><para><ulink url="http://www.mysql.com/documentation/">MySQL manual</ulink>,</para></listitem><listitem><para><ulink url="http://www.tldp.org/LDP/abs/html/x12265.html">A Brief Introduction to Regular Expressions</ulink>,</para></listitem><listitem><para><ulink url="http://httpd.apache.org/docs/mod/mod_rewrite.html">Apache Documentation of mod_rewrite</ulink>,</para></listitem><listitem><para><ulink url="http://www.w3.org/TR/2003/WD-css3-page-20031218/">CSS3 Paged Media Module</ulink>,</para></listitem><listitem><para><ulink url="http://newbiedoc.sourceforge.net">Debian Newbiedoc Project</ulink>.</para></listitem></itemizedlist></listitem><listitem><para>Matterform Media for providing <ulink url="http://www.matterform.com/qbullets/index.php">QBullets</ulink> for free.</para></listitem><listitem><para>Didi for <xref linkend="fig-optimize-php">.</para></listitem><listitem><para>Martin Kaspar for inspirating discussions on <application>PHP-Nuke</application> documentation.<indexterm><primary>documentation</primary></indexterm></para></listitem><listitem><para>All visitors of the <ulink url="http://www.karakas-online.de/phpnuke.html">Karakas Online <application>PHP-Nuke</application> Forum</ulink> for their kind remarks and suggestions for the improvement of the document, especially: nikits72, </para></listitem><listitem><para>Last, but not least, Gloomy for all the moral support during the hard times.</para></listitem></itemizedlist><para>The translators would like to thank the <ulink url="http://www.tldp.org">Linux Documentation Project (TLDP)</ulink> and its reviewers, especially Tabatha Marshall and Greg Ferguson for their comments and efforts to make this document available from TLDP's plattform<indexterm><primary>plattform</primary></indexterm> to a wider audience.</para></sect1>
<sect1 id="conventions"><title>Conventions</title><variablelist><varlistentry><term>admonitions
</term><listitem><para>Admonitions are little pictures used to emphasize something of importance to the reader. The four types used are:</para><note>
<title>Note</title>
<para>
Using a hammer to put together your computer is bad.
</para>
</note>
<tip>
<title>Tip</title>
<para>
Do not hit your thumb with the hammer, it hurts!
</para>
</tip>
<important>
<title>Important</title>
<para>
Watch where you're swinging that hammer!
</para>
</important>
<caution>
<title>Caution</title>
<para>
Hitting your thumb with a hammer may lead to an unwanted trip to the hospital!
</para>
</caution>
<warning>
<title>Warning</title>
<para>
Do not, under any circumstances, admit that you hit your own thumb with a hammer. The ridicule you will face is astounding!
</para>
</warning>
</listitem></varlistentry><varlistentry><term>Access&nbsp;keys
</term><listitem><para>Access keys enable navigation through the document, without relying on a mouse. The following keys have been given special meaning in this document:</para><variablelist><varlistentry><term>P
</term><listitem><para>Previous page.</para></listitem></varlistentry><varlistentry><term>N
</term><listitem><para>Next page.</para></listitem></varlistentry><varlistentry><term>H
</term><listitem><para>Home of the document (Table of Contents).</para></listitem></varlistentry><varlistentry><term>U
</term><listitem><para>Up (takes you one level up the section hierarchy).</para></listitem></varlistentry></variablelist><para>If you also happen to be reading the document from its original location, then the following access keys can also be used:</para><variablelist><varlistentry><term>S
</term><listitem><para>Start (takes you to the author's start page).</para></listitem></varlistentry><varlistentry><term>T
</term><listitem><para>The current (&ldquo;This&rdquo;) page, without the Sitemenu on the left.</para></listitem></varlistentry><varlistentry><term>M
</term><listitem><para>The current page in a frameset, where the left frame contains a Menu.</para></listitem></varlistentry></variablelist></listitem></varlistentry></variablelist><para>
To use the access keys, you have to simultaneously press a modifier key, which may vary from browser to browser. For example in NN6+/Mozilla, the modifier key is <keycap>ALT</keycap>, so you have to use
<keycombo>
<keycap>ALT</keycap>
<keycap>N</keycap>
</keycombo>
to go to the next page, and
<keycombo>
<keycap>ALT</keycap>
<keycap>P</keycap>
</keycombo>
to come back. In other browsers such as IE6, the access keys just give focus to the associated link, so the sequence becomes
<keycombo action='seq'>
<keycombo>
<keycap>ALT</keycap>
<keycap>N</keycap>
</keycombo>
<keycap>Enter</keycap>
</keycombo>
. Try it, you'll like it! <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_smile.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_smile.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_smile.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_smile.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject></para>
</sect1>
<sect1 id="book-behind-book"><title>The book behind the book</title><para>Do you want to create professionally formatted documents? Tired of always having to change the font settings, to insert or delete pagebreaks,<indexterm><primary>pagebreaks</primary></indexterm> to format your text for printing,<indexterm><primary>printing</primary></indexterm> monitor, or web view? Do you find yourself spending hours of your life into formatting issues that you wish you never had to be conftonted with? Did you, during your editing efforts, ever get the uncomforting feeling that you are inventing the wheel for th 39th time? </para><para>Well, in fact you are! You can use the power of Open Source tools like <ulink url="http://www.lyx.org">LyX</ulink> and <ulink url="http://www.sgmltools.org">sgmltools</ulink> to create the documents you've dreamed of, while, as a nice side effect, concentrating on what deserves most of your attention: Content,<indexterm><primary>Content</primary></indexterm> not Formatting! In <ulink url="http://www.karakas-online.de/mySGML/">Document processing with LyX and SGML</ulink>, <ulink url="http://www.karakas-online.de">Chris Karakas</ulink> describes a method by which all you have to do is to write your document in LyX, then run the .lyx file through a script that will produce the SGML<indexterm><primary>SGML</primary></indexterm> source and, from it, the HTML,<indexterm><primary>HTML</primary></indexterm> TXT, RTF, PDF and PS formatted documents (as in <xref linkend="formats">), complete with table of contents, embedded pictures, fonts, thumbnails<indexterm><primary>thumbnails</primary></indexterm> (for PDF) and other goodies - just as in the document you are reading right now!</para><para>That is, to learn how to produce a book like this one, you have to read <ulink url="http://www.karakas-online.de/mySGML/">the book behind the book</ulink>. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
<sect2 id="book-behind-book-general-idea"><title>The general idea </title><para>When writing LyX documents, formatting should be the last thing on your mind. Concentrate on writing a clear and c oncise document. The sgml parser will take care of the formatting.We've all heard of WYSIWYG.<indexterm><primary>WYSIWYG</primary></indexterm> <ulink url="http://www.lyx.org">LyX</ulink> is WYGIWYM.<indexterm><primary>WYGIWYM</primary></indexterm> WYGIWYM stands for &quot;What You Get Is What You Mean&quot;. This means if you mean for text to represent source code you assign it a source code environment (Lyxese for style), and it formats the way you meant it to. You needn't worry about formatting during the writing of your document. If you don't like the way it looks upon finishing and printing it out, you can change the way styles map to formatting, and those styles will consistently change throughout the document.</para></sect2>
<sect2 id="book-behind-book-line-of-attack"><title>Line of attack </title><para>The method described in <ulink url="http://www.karakas-online.de/mySGML/">Document processing with LyX and SGML</ulink> follows a line of attack defined by the following:</para><itemizedlist><listitem><para>We put everything in a shell script. We don't want to bother about anything else. We want to ponder comfortably upon the meaning of life while drinking some coffee or tea, watching our computer do the work for us - personally, a very rewarding experience :-)</para></listitem><listitem><para>We use <ulink url="http://www.gnu.org/software/sed/manual/sed.html">sed</ulink> to correct LyX' SGML output. The more we are able to correct, the more SGML features we get out of our plain vanilla LyX.<indexterm><primary>LyX</primary></indexterm></para></listitem><listitem><para>We use the <ulink url="http://www.sgmltools.org">sgmltools</ulink> package which hides a lot of details from the end user, giving nonetheless all the power of the involved tools.<footnote><para>The current version of the <ulink url="lyxtox">lyxtox</ulink> script make less use of sgmltools, due to the need of processing intermediate results for the integration of Mathematics, Bibliography etc. The originally used calls to sgmltools are nonetheless included in the comments of that script to demonstrate alternative ways of achieving the same result.</para></footnote></para></listitem><listitem><para>We will adapt the <ulink url="http://docbook.sourceforge.net/projects/dsssl/">DocBook DSSSL stylesheets</ulink> to our personal needs and taste.<indexterm><primary>taste</primary></indexterm>.</para></listitem><listitem><para>The end product shall be a directory ready to upload to our web server with all files, links, images and formats necessary.</para></listitem></itemizedlist><para>So you got appetite and want to delve into the gory details? Read the book behind this book: <ulink url="http://www.karakas-online.de/mySGML/">Document processing with LyX and SGML</ulink>! <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_cool.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_cool.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_cool.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_cool.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject></para>
</sect2>
</sect1>
<sect1 id="translate-php-nuke-howto"><title>How to translate this HOWTO</title><para>The <ulink url="http://www.karakas-online.de/EN-Book/">PHP-Nuke HOWTO</ulink> started also as a translation.<indexterm><primary>translation</primary></indexterm> You can read how it all started in <ulink url="http://www.nukeforums.com/forums/viewtopic.php?topic=11210&amp;forum=23">PHP-Nuke book translation thread</ulink> at nukeforums.com.<indexterm><primary>nukeforums.com</primary></indexterm></para><para>The best way to do the translation would be to install the <ulink url="http://www.lyx.org">LyX</ulink>. Chris still uses an old version (1.2.0) of it, but you could try the newest one and we will see if his <ulink url="http://www.karakas-online.de/mySGML/">document processing scripts</ulink> still work. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject></para>
<para>The process is the following (see, for example, <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=180">Greek Translation of Php-Nuke HOWTO</ulink> and <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=151">New language translation howto</ulink>): </para><orderedlist><listitem><para><indexterm><primary>Enumerate</primary></indexterm>You take the LyX version of the book from the Formats section (<xref linkend="formats">), you do the translation in LyX,<indexterm><primary>LyX</primary></indexterm> then send it to <ulink url="http://www.karakas-online.de">Chris Karakas</ulink> (chris at karakas-online dot de). </para></listitem><listitem><para><indexterm><primary>Enumerate</primary></indexterm>Chris will use his scripts (<xref linkend="book-behind-book">) to export the LyX document to SGML,<indexterm><primary>SGML</primary></indexterm> correct the SGML that comes out of LyX, then produce all other formats,<indexterm><primary>formats</primary></indexterm> as in <xref linkend="formats">).</para></listitem></orderedlist><para>The advantage of this method is that you only need to translate the words,<indexterm><primary>words</primary></indexterm> leaving everything else (like &quot;environments&quot;, SGML tags etc.) untouched. This way paragraphs, admonitions (see <xref linkend="conventions">), callouts (those small numbers in circles that you see in some code examples, as in <xref linkend="config-php-file">), code environments etc., all remain intact - and you don't need to recreate them.</para><para>We are in search of available volunteers to translate this book in as many languages as possible. In the case you are interested in translating this book, write to chris at karakas-online dot de, or <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=144">PHP-Nuke HOWTO</ulink>. Be prepared for months of hard work, as this is 500 pages of printed material!</para></sect1>
</chapter>
<chapter id="introduction"><title>Introduction to PHP-Nuke</title><sect1 id="purpose"><title>Purpose</title><para>There has always been the necessity to have a definitive guide on <application>PHP-Nuke</application>. Due to time constraints,<indexterm><primary>constraints</primary></indexterm> nobody has ever had the will to carry out this operation.<indexterm><primary>operation</primary></indexterm></para><para>Not any more! With this book, <application>PHP-Nuke</application> now posesses the most comprehensive guide on the subject,<indexterm><primary>subject</primary></indexterm> suitable for newbies and advanced users alike!</para></sect1>
<sect1 id="whatis-phpnuke"><title>What Is PHP-Nuke</title><para>PHP-Nuke is free software, released under the <ulink url="http://www.gnu.org/licenses/licenses.html">GNU License</ulink>.</para><para>It is a CMS (Content Managment System) that integrates in its inside all the instruments that are used to create, in a broad sense, an information<indexterm><primary>information</primary></indexterm> portal (<xref linkend="fig-php-nuke">). Given the immense number of present functions in the installation and in an even greater quantity of modules developed from third parties, the system<indexterm><primary>system</primary></indexterm> is also adept to the management of</para><itemizedlist><listitem><para>Intranet business,<indexterm><primary>business</primary></indexterm> </para></listitem><listitem><para>e-commerce systems, </para></listitem><listitem><para>corporate portals , </para></listitem><listitem><para>public agencies, </para></listitem><listitem><para>news agencies, </para></listitem><listitem><para>online companies, </para></listitem><listitem><para>information sites,</para></listitem><listitem><para>e-learning systems </para></listitem><listitem><para>and so on...</para></listitem></itemizedlist><para>
<figure id="fig-php-nuke">
<title>
phpnuke.org, the official <application>PHP-Nuke</application> site.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1003;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1003;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1003;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1003;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>phpnuke.org, the official <application>PHP-Nuke</application> site.</phrase>
</textobject>
<caption>
<para>phpnuke.org, the official <application>PHP-Nuke</application> site.</para>
</caption>
</mediaobject>
</figure>
</para><para>PHP-Nuke utilizes as hinge of its own structure the duo <ulink url="http://www.php.net">PHP</ulink>+ <ulink url="http://www.mysql.org">MySQL</ulink>, very often being accompanied by the <ulink url="http://www.apache.org">Apache</ulink> web server.<indexterm><primary>server</primary></indexterm> Many modules have integrated many other languages, such as Javascript,<indexterm><primary>Javascript</primary></indexterm> Java,<indexterm><primary>Java</primary></indexterm> Flash and also even systems that serve, through the portal, sounds and films in streaming mode (Online Radio,<indexterm><primary>Radio</primary></indexterm> TV Online, Images, Files...). From version 6.x onwards, the compatibility has been extended to include other databases as well, in order to extend the user base even more vastly. </para><para>PHP-Nuke is developed with a particular eye to the suggestions of the <ulink url="http://www.w3c.org">W3C</ulink>, in its origin,<indexterm><primary>origin</primary></indexterm> the code is in fact W3C compliant and one has validated both the code and the style sheets.<indexterm><primary>style sheets</primary></indexterm> It is then up to the user who intends to create a portal to adhere to these standards during the modification of the graphics or the intrinsic characteristics of the system.<indexterm><primary>system</primary></indexterm></para><para>The personalisation either of the graphical, or of the programming part has only a single limit, the fantasy and capability of the programmer and web designer.<indexterm><primary>designer</primary></indexterm>The presence of many <application>PHP-Nuke</application> sites similar to each other is due mainly to the lack of time of those who created them or the fear that the phase of personalisation is too difficult on a technical level. In fact, it suffices to let oneself be inspired by the available themes,<indexterm><primary>themes</primary></indexterm> in order to realize how easy it is to sew a new dress to one's portal.<indexterm><primary>portal</primary></indexterm></para><para>Francisco Burzi,<indexterm><primary>Burzi</primary></indexterm> father and mother of PHP-Nuke, describes his creation as follows:</para><blockquote><para>PHP-Nuke is a Web Portal System, storytelling software, News system,<indexterm><primary>system</primary></indexterm> online community or whatever you want to call it. The goal of <application>PHP-Nuke</application> is to have an automated web site to distribute news<indexterm><primary>news</primary></indexterm> and articles with users system.<indexterm><primary>system</primary></indexterm> Each user can submit comments to discuss the articles, just similar to Slashdot and many others. </para><para>Main features include: web based admin,<indexterm><primary>admin</primary></indexterm> surveys, top page, access stats page with counter,<indexterm><primary>counter</primary></indexterm> user customizable box, themes manager for registered users, friendly administration <acronym>GUI</acronym> with graphic topic manager,<indexterm><primary>manager</primary></indexterm> option to edit or delete stories, option to delete comments, moderation system,<indexterm><primary>system</primary></indexterm> Referers page to know who link us, sections manager,<indexterm><primary>manager</primary></indexterm> customizable HTML blocks, user and authors edit, an integrated Banners Ads system,<indexterm><primary>system</primary></indexterm> search engine, backend/headlines generation (RSS/RDF format), and many, many more friendly functions.</para><para>PHP-Nuke is written 100% in <acronym>PHP</acronym> and requires Apache Web server,<indexterm><primary>server</primary></indexterm> <acronym>PHP</acronym> and a SQL (MySQL, mSQL, PostgreSQL, ODBC, ODBC_Adabas,<indexterm><primary>ODBC_Adabas</primary></indexterm> Sybase or Interbase). Support for 25 languages, Yahoo like search engine,<indexterm><primary>engine</primary></indexterm> Comments option in Polls, lot of themes, Ephemerids manager, File Manager, Headlines, download<indexterm><primary>download</primary></indexterm> manager, faq manager, advanced blocks systems, reviews system, newsletter,<indexterm><primary>newsletter</primary></indexterm> categorized articles, multilanguage content management and a lot more.</para></blockquote></sect1>
<sect1 id="history"><title>Short history of PHP-Nuke</title><para>Francisco Burzi,<indexterm><primary>Burzi</primary></indexterm> describes the history of <application>PHP-Nuke</application> as follows:</para><blockquote><para>PHP-Nuke is a free software, released under the <ulink url="http://www.gnu.org/licenses/licenses.html">GNU GPL License</ulink>, version 2.0. <application>PHP-Nuke</application> is the result of many years administrating a news site called <ulink url="http://linuxpreview.org">Linux Preview</ulink>. First, around August 1998, I wrote my own code in <application>Perl</application> called NUKE and used it for about 1 year, then my site grew big, so I needed a more powerfull system and decided to use Slash,<indexterm><primary>Slash</primary></indexterm> the same used in the <ulink url="http://www.slashdot.org">Slashdot</ulink> site. It's good, but you realy need to know <application>Perl</application> to modify it, need too many modules,<indexterm><primary>modules</primary></indexterm> need to load a damn daemon that sucks all your <acronym>CPU</acronym> power. My Pentium III just appeared to be a 386 each minute the daemon made its work.</para><para>Well, then I discovered Thatware,<indexterm><primary>Thatware</primary></indexterm> a good project to have a news site under <acronym>PHP</acronym>.<indexterm><primary>PHP</primary></indexterm> I learned <acronym>PHP</acronym> in less than a week and began modifying it. There are too many mods to mention, it was practicaly a rewrite.<indexterm><primary>rewrite</primary></indexterm> I added some cool stuff, deleted some others and after more than 380 hours<indexterm><primary>hours</primary></indexterm> of hard work in 3 weeks! <application>PHP-Nuke</application> was born.</para><para>On August 17, 2000 I sold LinuxPreview.<indexterm><primary>Preview</primary></indexterm>org to LinuxAlianza.com and now I have all the time to dedicate to the development of <application>PHP-Nuke</application>.</para><para>From January 2001 to January 2002, <application>PHP-Nuke</application> has been financially supported by MandrakeSoft, the folks that made <productname>Mandrake</productname> <productname>Linux</productname>.<indexterm><primary>Linux</primary></indexterm> This gave me and <application>PHP-Nuke</application> a lot of oxygen and made possible a lot of stuff.</para><para>Now, I'm alone with this killer project.<indexterm><primary>project</primary></indexterm> There is a lot of help from the people that use and develop modules and themes.<indexterm><primary>themes</primary></indexterm> Now, <ulink url="http://phpnuke.oeg">phpnuke.org</ulink> is a big site with a lot of users and helpful information for any user around the world. There are also strong users community sites in almost any language you can imagine. Just go to <ulink url="http://phpnuke.oeg">phpnuke.org</ulink> and enjoy this great community! </para></blockquote></sect1>
<sect1 id="communities"><title>The <application>PHP-Nuke</application> Communities</title><para>A careful look is due to the true value of PHP-Nuke, that is the communities<indexterm><primary>communities</primary></indexterm> that you will find all around. Thanks to the voluntary job of these persons, of these sites, <application>PHP-Nuke</application> has become a well-known system and it is always thanks to them that <application>PHP-Nuke</application> is a multilanguage system that supports more than 25 languages. </para><para>Even the modules have been created mostly from developers in external communities and have, in second round, been included in new distributions of <application>PHP-Nuke</application>. </para><para>There are communities out there who are solely devoted to the creation of new graphical themes of PHP-Nuke, to technical support, file mirroring as well as a real lot of multilingual communities that take care of their members informing them in their local language, thus creating new personal ties and more focused projects. </para><itemizedlist><listitem><para><ulink url="http://www.nukeforums.com">Nukeforums.com</ulink>: Technical support to <application>PHP-Nuke</application>.</para></listitem><listitem><para><ulink url="http://www.nukecops.com">Nukecops</ulink>: Official <application>PHP-Nuke</application> development team.</para></listitem><listitem><para><ulink url="http://www.karakas-online.de/forum/phpnuke.html">Karakas-Online <application>PHP-Nuke</application> Forum</ulink>: Chris' <application>PHP-Nuke</application> Forum.<indexterm><primary>Forum</primary></indexterm></para></listitem><listitem><para><ulink url="http://www.nukedownloads.com">Nukedownloads.com</ulink>: File mirror for downloads.<indexterm><primary>ads</primary></indexterm></para></listitem><listitem><para><ulink url="http://www.nukeresources.com">nukeresources.com</ulink>: Downloads<indexterm><primary>ads</primary></indexterm></para></listitem><listitem><para><ulink url="http://www.nukefixes.com">nukefixes.com</ulink>: Fixes for <application>PHP-Nuke</application> bugs.<indexterm><primary>bugs</primary></indexterm></para></listitem><listitem><para><ulink url="http://www.nukesecurity.com">nukesecurity.com</ulink>: <application>PHP-Nuke</application> security.<indexterm><primary>security</primary></indexterm></para></listitem><listitem><para><ulink url="http://www.somara.com">Somara.com</ulink>: Themes and graphics.<indexterm><primary>graphics</primary></indexterm></para></listitem><listitem><para><ulink url="http://www.nukethemes.com">Nukethemes.com</ulink>: Themes and graphics.<indexterm><primary>graphics</primary></indexterm></para></listitem><listitem><para><ulink url="http://www.ecomjunk.com">Ecomjunk.com</ulink>: Addons and modules.<indexterm><primary>modules</primary></indexterm></para></listitem><listitem><para><ulink url="http://www.nukeaddn.com">Nukeaddn.com</ulink>: Addons and modules.<indexterm><primary>modules</primary></indexterm></para></listitem></itemizedlist><para>Communities in Italian language: </para><itemizedlist><listitem><para><ulink url="http://www.spaghettibrain.com">Spaghettibrain.com</ulink></para></listitem><listitem><para><ulink url="http://www.claudiodemarinis.it">Claudiodemarinis.it</ulink></para></listitem><listitem><para><ulink url="http://www.phpnuke.it">PHPnuke.it</ulink></para></listitem><listitem><para><ulink url="http://www.splatt.it">Splatt.it</ulink></para></listitem><listitem><para><ulink url="http://www.nukeitalia.com">Nukeitalia.com</ulink></para></listitem></itemizedlist><para>Thanks to the work of these portals and single persons we have more than 500 different modules and blocks that may be used to personalize our portal,<indexterm><primary>portal</primary></indexterm> in areas varying from the weather (<xref linkend="PHP-Nuke-Meteosat-block">) to e-commerce (<xref linkend="PHP-Nuke-eCommerce-module">), from gallery (<xref linkend="PHP-Nuke-Gallery-module">) to chat realized in flash and videogames in Java,<indexterm><primary>Java</primary></indexterm> all included in the layout of <application>PHP-Nuke</application>. </para></sect1>
<sect1 id="whyphpnuke"><title>Why use <application>PHP-Nuke</application> and not static HTML pages</title><itemizedlist><listitem><para>Because managing large sites with only static HTML pages is dangerous for your health.</para></listitem><listitem><para>Because through the dynamic pages, users can interact (Forum,<indexterm><primary>Forum</primary></indexterm> chat)</para></listitem><listitem><para>Because through the dynamic pages we can offer value added services (restricted areas, various services based on user classification.<indexterm><primary>classification</primary></indexterm>..) </para></listitem><listitem><para>Because the information is more easily catalogued.</para></listitem><listitem><para>Because with a few <acronym>PHP</acronym> pages we recall a lot of information.<indexterm><primary>information</primary></indexterm></para></listitem><listitem><para>Because keeping the contents up-to-date does not demand particular technical expertise and can be managed by anyone (by Davis Batistes).</para></listitem><listitem><para>It is the simplest way to pull over a complete portal,<indexterm><primary>portal</primary></indexterm> thanks to its open source engine,<indexterm><primary>engine</primary></indexterm> it allows anyone to implement new modules or to modify and to personalize existing modules.<indexterm><primary>modules</primary></indexterm> (by Micione,<indexterm><primary>Micione</primary></indexterm> <ulink url="http://www.vizzani.net">www.vizzani.net</ulink>)</para></listitem><listitem><para>It is very intuitive and easy to learn (by Anonymous)</para></listitem><listitem><para>It is easy to modify by those who intend to personalize the program (By Arus)</para></listitem><listitem><para>It is easy to use by the lesser experts among us.</para></listitem></itemizedlist></sect1>
<sect1 id="PHP-Nuke-forks"><title>The <application>PHP-Nuke</application> forks</title><para>There are several CMS systems, which are PHPNuke forks;<indexterm><primary>forks</primary></indexterm> among the most famous, we can mention <ulink url="http://www.postnuke.com">Post-Nuke</ulink>, <ulink url="http://sourceforge.net/projects/envolution">Envolution</ulink>, <ulink url="http://sourceforge.net/projects/myphpnuke">MyPHPNuke</ulink> and <ulink url="http://www.xoops.org">Xoops</ulink>.</para><sect2 id="PHP-Nuke-vs-Post-Nuke"><title>PHP-Nuke vs. Post-Nuke</title><para>Post-Nuke is another Content Management System (CMS) similar to <application>PHP-Nuke</application>. Whilst PostNuke is a fork of PHP-Nuke, the entire core of the product has been replaced, with the aim of making it more secure and stable, and able to work in high-volume environments with ease.</para><para>Some of the highlights of PostNuke are, according to its developers (in <ulink url="http://developing.postnukemodules.com">Post-Nuke Modules</ulink>):</para><itemizedlist><listitem><para>Customisation of all aspects of the website's appearance through themes,<indexterm><primary>themes</primary></indexterm> including CSS support.</para></listitem><listitem><para>The ability to specify items as being suitable for either a single or all languages.</para></listitem><listitem><para>The best guarantee of displaying your webpages on all browsers due to HTML<indexterm><primary>HTML</primary></indexterm> 4.01 transitional compliance.<indexterm><primary>compliance</primary></indexterm></para></listitem><listitem><para>A standard API and extensive documentation to allow for easy creation of extended functionality through modules and blocks.</para></listitem></itemizedlist><para>The merits of Post-Nuke, as compared to those of PHP-Nuke, have been subject of controversial discussion among fans of both CMSs. We cannot give an objective opinion, since we are biased towards <application>PHP-Nuke</application>. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> However, we will try to give you an idea:</para>
<para>Even its critics will agree that, for a portal whose purpose is to make information publicly accessible,<indexterm><primary>accessible</primary></indexterm> <application>PHP-Nuke</application> is a very good solution. In comparison to Post-Nuke,<indexterm><primary>Post-Nuke</primary></indexterm> most people will also find that <application>PHP-Nuke</application> has many more modules available. However, some will argue that most of them seem geared toward the average end user and not a business or corporate environment.</para><para>On the plus side, PostNuke has a very detailed strict user permissions system allowing you to limit access to every module and area of your site to a general group or a specific user. The permissions system allows you to create groups and users with special permissions. You can add a user to one or many of these groups to give a variety of complex permissions easily. This is handy if you need moderators, sub admins, and other people helping manage a commercial site and wish to limit admin access. This may make PostNuke more appealing to a professional site - but see the Your Account Tweak module (<xref linkend="NSN-Your-Account-Tweak-module">), the Approve Membership module ( <xref linkend="PHP-Nuke-Approve-Membership-module">), the eCommerce modules (<xref linkend="PHP-Nuke-eCommerce-module">) or the Project Management WorkBoard module (<xref linkend="PHP-Nuke-WorkBoard-module">) before you draw premature conclusions. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
<para>Here are some PostNuke modules that are popular among business end users:</para><itemizedlist><listitem><para><ulink url="http://pnapi.com">Xanthia Theme Engine</ulink></para></listitem><listitem><para><ulink url="http://pn.arising.net/ce">ContentExpess Content management</ulink></para></listitem><listitem><para><ulink url="http://postnuke.wunderlin.net">Static Content Management</ulink></para></listitem><listitem><para><ulink url="http://postcalendar.tv">PostCalendar</ulink></para></listitem><listitem><para><ulink url="http://www.stutchbury.net">FormExpress Forms Generator</ulink></para></listitem><listitem><para><ulink url="http://smiatek.com">pnAddressBook (Palm Style)</ulink></para></listitem><listitem><para><ulink url="http://www.olos.nl">LDAP</ulink></para></listitem><listitem><para><ulink url="http://www.sitescandinavia.net">NukeOWL</ulink></para></listitem><listitem><para><ulink url="http://www.itsallbutstraw.com">PNphpBB2</ulink></para></listitem></itemizedlist><para>However, PostNuke seems to be caught prisoner of its own development impetus:<indexterm><primary>impetus</primary></indexterm> it changed so fast, so often, and made code break backward compatibility<indexterm><primary>compatibility</primary></indexterm> in newer versions so often, that it became difficult even for seasoned webmasters to follow it. Lack of compatibility even between adjacent versions and rumours on its development being suspended, has robbed the nerve of quite a few people, who then turned back to <application>PHP-Nuke</application> for its great community,<indexterm><primary>community</primary></indexterm> support, continuing, smooth development and vast collection of modules.<indexterm><primary>modules</primary></indexterm> The following quote,<indexterm><primary>quote</primary></indexterm> taken from <ulink url="http://www.nukecops.com/article65.html">History of <application>PHP-Nuke</application> and Post-Nuke</ulink>, reflects this situation:</para><blockquote><para>I spent a month trying to customize Post-Nuke for a client, and then I gave up. It was too hard and the support was non-existent. Although you'll find many people in the community who want to help you, you'll find no one who has experience with the particular version you've got.</para></blockquote><note>
<title>
Is Post-Nuke more secure than PHP-Nuke?
</title>
<para>
The security argument is often heard in favour of Post-Nuke. However, a commited cracker will probably not encounter considerably more difficulties in cracking Post-Nuke, than PHP-Nuke, as the following testimonial, taken from the discussion in <ulink url="http://www.nukecops.com/article65.html">History of <application>PHP-Nuke</application> and Post-Nuke</ulink>, illustrates:
</para>
<blockquote><para>
I have a fair few associates who are still hackers, and they can crack into any Post-Nuke site in 20 seconds flat - I've timed them - and they've had full - note: FULL access to the administration section when they have. The fastest I've seen them hack the least secure <application>PHP-Nuke</application> over the past year, is 30 seconds approx. (32 seconds to be precise). That doesn't sound like <application>PHP-Nuke</application> is less secure to me.
</para>
<para>
The latest version of <application>PHP-Nuke</application> (6.5) prior to it's RC1 with the new security procedures in it, it took them 5 minutes to hack into it.
</para>
</blockquote>
</note>
<para>Of course, 5 minutes will not make you sleep any more quiet than with Post-Nuke,<indexterm><primary>Post-Nuke</primary></indexterm> but the Web is a dangerous place by construction and and the point is of relative, not absolute nature.<indexterm><primary>nature</primary></indexterm> <application>PHP-Nuke</application> has improved its security even more since then. For more details on <application>PHP-Nuke</application> security,<indexterm><primary>security</primary></indexterm> we refer you to <xref linkend="how-secure-is-php-nuke">, where we will talk about PHP-Nuke's past security vulnerabilities,<indexterm><primary>vulnerabilities</primary></indexterm> its new security procedures and what you can do to enhance its security even further.</para><para>We cannot go into more details on PostNuke, since they would easily fill another book. Perhaps the best test is to visit the homepages of both projects, <ulink url="http://phpnuke.org">PHP-Nuke</ulink> and <ulink url="http://www.postnuke.com">PostNuke</ulink> - and decide for yourself which one you like best. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_smile.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_smile.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_smile.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_smile.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
</sect2>
<sect2 id="PHP-Nuke-vs-XOOPS"><title>PHP-Nuke vs. XOOPS</title><para><ulink url="http://www.xoops.org">XOOPS</ulink> is a dynamic OO (Object Oriented) based open source portal script written in <acronym>PHP</acronym>.<indexterm><primary>PHP</primary></indexterm> According to its developers, XOOPS is the &ldquo;ideal tool for developing small to large dynamic community websites, intra-company portals,<indexterm><primary>portals</primary></indexterm> corporate portals,<indexterm><primary>portals</primary></indexterm> weblogs and much more&rdquo; (see <ulink url="http://www.xoops.org/general/index.php">About XOOPS</ulink>). The developers also tell the following about their goals:</para><blockquote><para>The goal of the XOOPS team is to create a Content Management System (CMS) for users and developers that installs out of the box offering unparalleled ease of use, support and management.<indexterm><primary>management</primary></indexterm> The XOOPS CMS will be extendable by the use of modules installable through a unified admin interface.<indexterm><primary>interface</primary></indexterm> The ultimate goal of the XOOPS team is to take the best features of current CMS's and roll them into an Open Source CMS that's easy to use, extendable and unparalleled in the Free/Open Source Community.</para></blockquote><para>XOOPS is (see <ulink url="http://www.xoops.org/general/features.php">XOOPS Features List</ulink>):</para><itemizedlist><listitem><para>Database-driven: XOOPS uses relational databases (currently MySQL) to store data required for running a web-based content management system (compare with <xref linkend="whatis-phpnuke">).</para></listitem><listitem><para>Fully Modularized: Modules can be installed/uninstalled/ativated/deactivated<indexterm><primary>activated</primary></indexterm> with a click using the XOOPS module administration system (compare with <xref linkend="module-management">).</para></listitem><listitem><para>Personalization: Registered users can edit their profiles, select site themes,<indexterm><primary>themes</primary></indexterm> upload custom avatars,<indexterm><primary>avatars</primary></indexterm> and much more (compare with <xref linkend="frontend">)!</para></listitem><listitem><para>User Management: The ability to search for users by various criteria,<indexterm><primary>criteria</primary></indexterm> send email and private messages to users through a template-based messaging system (compare with <xref linkend="fig-private-messages">).</para></listitem><listitem><para>Supported World-wide:<indexterm><primary>World-wide</primary></indexterm> The XOOPS community has more than dozen official support sites around the world for support of non-English speaking users (compare with <xref linkend="communities">).</para></listitem><listitem><para>Multi-byte Language Support: Fully supports multi-byte languages, including Japanese,<indexterm><primary>Japanese</primary></indexterm> Simplified and Traditional Chinese, Korean, etc (compare with <xref linkend="modifying-PHP-Nuke-texts">).</para></listitem><listitem><para>Versatile Group Permissions System: Powerful and user-friendly permissions<indexterm><primary>permissions</primary></indexterm> system which enables administrators to set permissions by group (compare with <xref linkend="NSN-Your-Account-Tweak-module">).</para></listitem><listitem><para>Theme-based skinnable interface: XOOPS is driven by a powerful theme system.<indexterm><primary>system</primary></indexterm> Both admins and users can change the look of the entire web site with just a click of a mouse. There are also over 60 themes available for download (compare with <xref linkend="customization">)!</para></listitem></itemizedlist><para>The OO (Object Oriented) approach of XOOPS to Web Content Management is innovative, but also controversial. Franzisco Burzi writes in <ulink url="http://www.nukecops.com/article65.html">History of <application>PHP-Nuke</application> and Post-Nuke</ulink>:</para><blockquote><para>About saying that OOP (Object Oriented Programming) is a good stuff and makes stuff more stable, modular, or whatever else you want... False. OOP is good for very big projects, which is not the case of <application>PHP-Nuke</application> (I mean VERY BIG projects) with a lot of reusable code. BUT... any good <acronym>PHP</acronym> programmer knows that the use (or worse, the intense use) of objects/classes in a <acronym>PHP</acronym> script isn't good. <acronym>PHP</acronym> is not efficient managing objects/classes. At least it's less efficient than managing custom user created functions. Any decent <acronym>PHP</acronym> 4 book will say this to you: If you can manage to have your software working without using OOP,<indexterm><primary>OOP</primary></indexterm> there isn't any reason to use objects, because of performance issues.</para></blockquote></sect2>
<sect2 id="XOOPS-vs-Post-Nuke"><title>XOOPS vs. Post-Nuke</title><para>We cannot go into the details of a comparison between XOOPS and Post-Nuke,<indexterm><primary>Post-Nuke</primary></indexterm> as this would be rather off-topic here. For a discussion of XOOPS vs. Post-Nuke,<indexterm><primary>Post-Nuke</primary></indexterm> see <ulink url="http://www.xoops.org/modules/newbb/viewtopic.php?topic_id=14536&amp;forum=3">XOOPS vs. Post-Nuke</ulink>. There, among lists of pros and contras, you will read this:</para><blockquote>
<para>
I'm an architect. My teacher always told me that there are no "bad tools". There are only "bad craftsmen".
</para>
<para>
Find your own way to work - it's not a race, not a competition, you don't need to have the better machine to win. The best sites won't flash with decorations, tons of blocks and gifs. They are made with the same basic tools, CLEAR AND WISE IDEA, and lots of custom made details.
</para>
<para>
Innovate - not imitate. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_smile.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_smile.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_smile.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_smile.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject>
</para>
</blockquote>
</sect2>
</sect1>
</chapter>
<chapter id="installation"><title>How to install PHP-Nuke</title><para>The screenshots regarding the installation procedure,<indexterm><primary>procedure</primary></indexterm> contrary to those of the other chapters, refer to the <productname>Windows</productname> platform. This is so in an effort to reduce the number of misunderstandings and ulterior<indexterm><primary>ulterior</primary></indexterm> help requests from the <productname>Windows</productname> community.<indexterm><primary>community</primary></indexterm> (Judging from the feedback we receive, the <productname>Linux</productname> and FreeBSD community<indexterm><primary>community</primary></indexterm> seem to be more able to deal with installation problems in this respect). </para><para>For the installation of <ulink url="http://www.php.net">PHP</ulink>+ <ulink url="http://www.mysql.org">MySQL</ulink>+ <ulink url="http://www.apache.org">Apache</ulink>, <ulink url="http://www.phpmyadmin.net/">PHPMyAdmin</ulink> etc. refer to <xref linkend="tools"> where you will find notes and links to useful tools in order to emulate<indexterm><primary>emulate</primary></indexterm> <application>PHP-Nuke</application> on your client.</para><para>These instructions are valid for all <application>PHP-Nuke</application> versions from 6.0 onwards.</para><sect1 id="prerequisites"><title>Prerequisites</title><para>In the INSTALL file of PHP-Nuke, we read the following about its requirements:<indexterm><primary>requirements</primary></indexterm></para><blockquote><para>In order to setup <application>PHP-Nuke</application> the folowing prerequisits are necessary.</para><itemizedlist><listitem><para><ulink url="http://www.linux.com">Linux</ulink>, installed and working properly.</para></listitem><listitem><para><ulink url="http://www.apache.org">Apache Web Server</ulink>.</para></listitem><listitem><para><ulink url="http://www.php.net">PHP</ulink> version 4.1.x or better (mod_php) Apache module.<indexterm><primary>module</primary></indexterm></para></listitem><listitem><para><ulink url="http://www.mysql.com">MySQL database server</ulink></para></listitem></itemizedlist><para>...The above doesn't mean it will not work with other configurations,<indexterm><primary>configurations</primary></indexterm> OS's, DB's, etc, but we only provide INSTALL instructions for the above configuration.<indexterm><primary>configuration</primary></indexterm> In fact <application>PHP-Nuke</application> works under <productname>Windows</productname> (all), FreeBSD, OS/2, MacOS,<indexterm><primary>MacOS</primary></indexterm> etc.</para></blockquote><important>
<title>
PHP 4.1.0 or later needed!
</title>
<para>
From the INSTALL file, we see that you must have at least <acronym>PHP</acronym> 4.1.0 to use <application>PHP-Nuke</application> 6.5 and later. This is an important piece of information that you should ckeck before proceeding. See <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=36">Warning: Invalid argument supplied for foreach()</ulink>.
</para>
</important>
<para>You see, it is always a good idea to read the INSTALL file that comes with a software package.<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
<para>To see the <acronym>PHP</acronym> version you are running and do also a small test on your configuration,<indexterm><primary>configuration</primary></indexterm> you can run the test.php file as described in <xref linkend="test-php">.</para><note>
<title>
PHP-Nuke and databases other than MySQL
</title>
<para>
From <application>PHP-Nuke</application> version 5.3, Francisco added a new SQL abstraction layer. It enables <application>PHP-Nuke</application> to support databases other than MySQL, like mSQL, PostgreSQL, PostgreSQL_local, ODBC, ODBC_Adabas, Sybase and Interbase.
</para>
</note>
<para>For the Microsoft Internet Informaion Server (IIS), some tests we have done were positive, some others indicated that a special configuration was needed.</para></sect1>
<sect1 id="installation-process"><title>Installation process</title><sect2 id="download"><title>Download</title><para>Well... there is little to say here, it suffices to go to a site that holds the files and download them. There is only a small remark to make: if you use <productname>Windows</productname> and download a version comprised of a file with the ending tar.gz, do not worry, your <ulink url="http://www.winzip.com">Winzip</ulink> supports it without problems. Once downloaded, extract it and &ldquo;throw&rdquo; all its contents in a folder you created for this purpose and you call &ldquo;Nuke6<indexterm><primary>Nuke6</primary></indexterm>&rdquo; or whatever ( sites from which you can download <application>PHP-Nuke</application> are: <ulink url="http://phpnuke.org">phpnuke.org</ulink>, <ulink url="http://www.spaghettibrain.com">www.spaghettibrain.com</ulink> etc.).</para></sect2>
<sect2 id="upload"><title>Upload through FTP</title><para>Well, now what remains is just to upload the files to the interior of our main server directory that resides on our provider.<indexterm><primary>provider</primary></indexterm> </para><caution>
<title>
Attention!
</title>
<para>
It is highly recommended, prior to any installation steps, to verify that your provider supports <ulink url="http://www.php.net">PHP</ulink> and <ulink url="http://www.mysql.org">MySQL</ulink>.
</para>
</caution>
<para>Your ISP has already given you:</para><itemizedlist><listitem><para>An FTP user and password:<indexterm><primary>password</primary></indexterm> you need these for the file transfers.</para></listitem><listitem><para>A database user and password, as well as the name of the database server<indexterm><primary>server</primary></indexterm> to connect to: you need them to connect your applications (like PHP-Nuke) to the database and to be able to access the administration panel of phpMyAdmin<indexterm><primary>Admin</primary></indexterm> (<xref linkend="phpmyadmin">).</para></listitem></itemizedlist><para>For FTP in the <productname>Windows</productname> plattform,<indexterm><primary>plattform</primary></indexterm> we recommend using the <ulink url="http://www.ftpplanet.com/ftpresources/ftpmain.htm">WS_FTP</ulink> application.<indexterm><primary>application</primary></indexterm> It is free for personal use and you can download it from download.<indexterm><primary>download</primary></indexterm>com by entering the search key &ldquo;ws_ftp<indexterm><primary>ws_ftp</primary></indexterm>&rdquo;. For the <productname>Linux</productname> plattform instead, we recommend GFTP (free for all and preinstall<indexterm><primary>preinstall</primary></indexterm>ed in all distributions), which can be run from the command line by simply typing &ldquo;gftp<indexterm><primary>gftp</primary></indexterm>&rdquo;.</para><para>
<figure id="fig-ws-ftp-general">
<title>
WS_FTP: General connection parameters.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1004;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1004;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1004;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1004;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>WS_FTP: General connection parameters.</phrase>
</textobject>
<caption>
<para>WS_FTP: General connection parameters.</para>
</caption>
</mediaobject>
</figure>
</para><para>The use of an FTP program is very simple - we will follow the procedure<indexterm><primary>procedure</primary></indexterm> through 4 screens that enable us to:</para><itemizedlist><listitem><para>Connect (<xref linkend="fig-ws-ftp-general">)</para></listitem><listitem><para>Transfer files (<xref linkend="fig-ws-ftp-local-remote">)</para></listitem><listitem><para>Set up the permissions (see also <xref linkend="permissions">)</para></listitem><listitem><para>(Eventually) edit the uploaded files</para></listitem></itemizedlist><para><xref linkend="fig-ws-ftp-general"> shows the WS_FTP General Connection Parameters screen.<indexterm><primary>screen</primary></indexterm> Entering the right values in the fields of that screen will enable you to conncet to the server where you want to upload the files.</para><caution>
<title>
Attention!
</title>
<para>
If you are installing <application>PHP-Nuke</application> locally, it is not necessary to use FTP! In this case, it suffices to copy the files into the right directory. In case you are working under Linux, it may be necessary to set the right file permissions. See <xref linkend="permissions"> on how to do this.
</para>
</caution>
<para>
<figure id="fig-ws-ftp-local-remote">
<title>
WS_FTP: Main screen with local and remote windows.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1005;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1005;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1005;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1005;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>WS_FTP: Main screen with local and remote windows.</phrase>
</textobject>
<caption>
<para>WS_FTP: Main screen with local and remote windows.</para>
</caption>
</mediaobject>
</figure>
</para><para>Once connected, the next operation is to upload the files on the remote server.<indexterm><primary>server</primary></indexterm> With WS_FTP,<indexterm><primary>WS_FTP</primary></indexterm> as well as woth the majority of the other FTP clients, the window that contains the local files is located to the left, while the remote files are displayed in a window to the right (<xref linkend="fig-ws-ftp-local-remote">). You have to position your cursor on the directory that contains the files to be uploaded to the left and the directory tha has to receive them on the remote host to the right. You can do this through the graphical interface of WS_FTP.<indexterm><primary>WS_FTP</primary></indexterm></para><para>As you can see in <xref linkend="fig-ws-ftp-local-remote">, there are also some function buttons there: the two arrows are used to upload / download files to / from the server,<indexterm><primary>server</primary></indexterm> the other two buttons that are functionally important are &ldquo;MkDir&rdquo;, which creates a new directory, and &ldquo;Refresh<indexterm><primary>Refresh</primary></indexterm>&rdquo;, which updates the view of data contained in a window.</para><para>Don't upload all extracted files. After extraction,<indexterm><primary>extraction</primary></indexterm> you will find a structure similar to the one depicted in <xref linkend="fig-file-structure">.</para><para>
<figure id="fig-file-structure">
<title>
<application>PHP-Nuke</application> 6.0 file structure
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1006;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1006;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1006;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1006;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>PHP-Nuke 6.0 file structure</phrase>
</textobject>
<caption>
<para>PHP-Nuke 6.0 file structure</para>
</caption>
</mediaobject>
</figure>
</para><para>You don't need to upload all the files from the folder, in the main directory of your web presence you will only need to upload the contents of the html folder (so just do a doubleclick on the html folder and upload everything that is inside it). But in order to populate the database with the <application>PHP-Nuke</application> tables,<indexterm><primary>tables</primary></indexterm> you will also need to upload the sql folder too. After the database creation (see <xref linkend="database-creation">), you should delete this folder though - for security reasons.</para><para>An operation that may be useful in cases of emergency is &ldquo;Edit<indexterm><primary>Edit</primary></indexterm>&rdquo;, which is accessible from the context menu after a right click with the mouse on the desired file. &ldquo;Edit<indexterm><primary>Edit</primary></indexterm>&rdquo; will allow a direct modification of the file, without the intermediate step of downloading it to your computer.</para></sect2>
<sect2 id="permissions"><title>File permissions</title><important>
<title>Important</title>
<para>
This process only really applies if your <application>PHP-Nuke</application> will be installed on a Linux/Unix server, if instead you will install it on <productname>Windows</productname> operating systems you don't have to do anything.
</para>
</important>
<variablelist><varlistentry><term>Permissions:
</term><listitem><para>Each file or directory<footnote><para>directories are just special files in Linux</para></footnote> has 3 groups of permissions associated with it: one set of Read, Write or Execute permissions for the owner (also called &ldquo;user&rdquo; in this context), a group and &quot;others&quot; respectively. The owner in our case should be the user name of your web server.<indexterm><primary>server</primary></indexterm> The group is a user group the web server is a member of. And &ldquo;others&rdquo; are just &ldquo;the rest&rdquo;. </para></listitem></varlistentry></variablelist><para>File permissions are usually grouped together in groups of three, like this: (rwx)(rwx)(rwx). The first group are the user permissions, the second one the group permissions<indexterm><primary>permissions</primary></indexterm> and the third one the permissions for &ldquo;others&rdquo;. A good mnemonic for this grouping is UGO (User,<indexterm><primary>User</primary></indexterm> Group, Others). Inside each permissions group, a certain permission may or may not be present. Thus, the user (owner) of the file will usually have read and write permissions<indexterm><primary>permissions</primary></indexterm> (and execute permission too, if the file is executable), but the group permissions may only allow read access and &ldquo;others&rdquo; may not be allowed to access the file at all, neither for reading, nor for writing or execution.</para><para>If you imagine that the existence of a permission is denoted by a 1, while its absence by a 0, then you end up with a representation like (111)(111)(111), where all permissions are present for all, or (000)(000)(000), where they are absent for all. Of course, any other combination is possible, for example (111)(110)100), which denotes read, write and execute permissions for the user (all 1s are present in the first grouping: (111)), read and write permissions for the group (only the first and second 1s are there in the second grouping (110)) and read permission for others (since only the first 1 is there, while the rest are 0s in the third grouping (100)).</para><para>Writing down a sequence of nine 0s and 1s is not very practical, so one came with the idea to interprete each one of the three groupings as a binary number. A (111) would thus mean a 7, a (110) a 6, a (100) a 4. Taken together, the sequence (111)(110)100) of the example above would be represented by the number 764.<indexterm><primary>764</primary></indexterm> That's compact and widely used.</para><para>Unfortunately, it is also very cryptic,<indexterm><primary>cryptic</primary></indexterm> since most people didn't have much exposure to the binary number system at school, not to mention everyday life. How is one going to understand instructions like &ldquo;set file permissions to 644<indexterm><primary>644</primary></indexterm>&rdquo; then?</para><para>Luckily, there exists an easy mnemonic for this: &ldquo;4,2,1&rdquo;, that is the first 1 counts as a 4, the second as a 2 and the third one as 1 - a 0 is always a 0, by the way, even in the binary system. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
<para>Whenever you see a 1 in the first position of a permissions triple, you add a 4, whenever you see one in the second, you add a 2 and if you see it in the third, you add 1. You do this for UGO, that is for User,<indexterm><primary>User</primary></indexterm> Group and Others and you end up with a three digit number that represents the permissions of the file.</para><para>Most of the time, however, you will be busy deciphering permissions,<indexterm><primary>permissions</primary></indexterm> rather than formulating them yourself in this cryptic manner. So how do you go about interpreting a permissions representation like 764<indexterm><primary>764</primary></indexterm> that was given to you in a document like the <ulink url="http://www.karakas-online.de/EN-Book/">PHP-Nuke HOWTO</ulink>? </para><para>For this, you will need to develop a &ldquo;feeling&rdquo; of how each of the three numbers (7, 6 and 4 in this example) can be written as a unique sum of 4s, 2s and 1s. For example 7 is 4+2+1, 6 is 4+2 and 4 is just 4. A 4 in the sum represents a 1 in the leftmost position. If a 4 is not present in the sum, the leftmost position is a 0. A 2 in the sum reperesents a 1 in the middle position - if there is no 2 in the sum, you just write a 0 there. Finally, a 1 in the sum represents a 1 in the rightmost position, while if there is no 1 in the sum, you write a 0 there.</para><para>Now if you remember that the leftmost 1 or 0 in a pattern like (111) denotes<indexterm><primary>notes</primary></indexterm> a read permission or the absence or it, a 1 or a 0 in the middle position denotes<indexterm><primary>notes</primary></indexterm> a write permission or its absence and a 1 or 0 in the leftmost position denotes<indexterm><primary>notes</primary></indexterm> an execute permission or its absence, then you can take a permissions represenation like 764 above, see that 7=4+2+1 and realize that it means (111), see that 6=4+2 (or 4+2+0, if you like) and realize that it means (110), finally see that 4=4 (or 4+0+0) and realize that it stands for (100), and you can see that 764 is equivalent to (111)(110)(100), meaning read, write and execute permissions for the user (owner), read and write permissions for the group and only read permissions for others.
</para><para>Easy after all, isn't it? <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
<para>For more information on permissions,<indexterm><primary>permissions</primary></indexterm> see:</para><itemizedlist><listitem><para><ulink url="http://www.washington.edu/computing/web/publishing/permissions.html">Setting Unix Permissions For Web Pages</ulink></para></listitem><listitem><para><ulink url="http://www.onlamp.com/pub/a/bsd/2000/09/06/FreeBSD_Basics.html">An Introduction to Unix Permissions</ulink></para></listitem><listitem><para><ulink url="http://www.perlfect.com/articles/chmod.shtml">Understanding <productname>UNIX</productname> permissions and chmod</ulink></para></listitem><listitem><para><ulink url="http://www.nyu.edu/webguide/permissions.html">Tutorial: <productname>UNIX</productname> Permissions</ulink></para></listitem></itemizedlist><para>Setting up permissions on files serves the purpose of having them execute only certain operations (write, execute etc.) when called. Setting them up correctly is important for <application>PHP-Nuke</application> to operate in its full functionality.<indexterm><primary>functionality</primary></indexterm> </para><para>The right permissions for <application>PHP-Nuke</application> are the following (for the base permissions,<indexterm><primary>permissions</primary></indexterm> see <xref linkend="permissions2"> in the context of security): </para><itemizedlist><listitem><para>Files: 644<indexterm><primary>644</primary></indexterm></para></listitem><listitem><para>Directories:<indexterm><primary>Directories</primary></indexterm> 755</para></listitem></itemizedlist><para>Only directories that require upload access (like the forum's avatar folder, if you allow avatar upload) should be set to 777 and files that get data<indexterm><primary>data</primary></indexterm> written to them by the program should be set to 666.<indexterm><primary>666</primary></indexterm> </para><para>With <ulink url="http://www.ftpplanet.com/ftpresources/ftpmain.htm">WS_FTP</ulink> you must select the files or folders on which you want to impose the permission<indexterm><primary>permission</primary></indexterm>s and, with the right mouse key,<indexterm><primary>key</primary></indexterm> to select the option &ldquo;chmod (UNIX)&rdquo; (see <xref linkend="fig-ws-ftp-chmod-1">).</para><para>
<figure id="fig-ws-ftp-chmod-1">
<title>
WS_FTP context menu on right mouse click: chmod (UNIX)
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1007;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1007;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1007;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1007;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>WS_FTP context menu on right mouse click: chmod (UNIX)</phrase>
</textobject>
<caption>
<para>WS_FTP context menu on right mouse click: chmod (UNIX)</para>
</caption>
</mediaobject>
</figure>
</para><para>The window &ldquo;Remote file permissions<indexterm><primary>permissions</primary></indexterm>&rdquo; will appear (see <xref linkend="fig-ws-ftp-chmod-2">). To change the permissions on a directory as required to 755,<indexterm><primary>755</primary></indexterm> for example, check the boxes as shown in <xref linkend="fig-ws-ftp-chmod-2"> and press &ldquo;OK&rdquo;.</para><para>
<figure id="fig-ws-ftp-chmod-2">
<title>
WS_FTP Remote file permissions window
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1008;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1008;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1008;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1008;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>WS_FTP Remote file permissions window</phrase>
</textobject>
<caption>
<para>WS_FTP Remote file permissions window</para>
</caption>
</mediaobject>
</figure>
</para><para>This procedure will cost you some time, but it is very important to carry out. Moreover, you will have to do it every time you insert a new file or module<indexterm><primary>module</primary></indexterm> to your <application>PHP-Nuke</application>. </para></sect2>
<sect2 id="database-creation"><title>Database creation</title><para>Create a database that will contain the <application>PHP-Nuke</application> tables.<indexterm><primary>tables</primary></indexterm> The name of the database should be the same name as the one you entered in config.<indexterm><primary>config</primary></indexterm>php (see <xref linkend="config-php-file">):</para><screen><![CDATA[mysqladmin create nuke
]]></screen><para>To populate the database,<indexterm><primary>base</primary></indexterm> you have to run the nuke.sql file &ldquo;through&rdquo; mysql. Change to the sql directory and do from the command line:</para><screen><![CDATA[mysql -h dbhost -u dbuname -p dbname < nuke.sql
]]></screen><para>where dbhost,<indexterm><primary>dbhost</primary></indexterm> dbuname and dbname are the database host, database username and database name, exactly as entered in config.php.<indexterm><primary>config.php</primary></indexterm> Just as you import nuke.sql,<indexterm><primary>nuke.sql</primary></indexterm> you can import any other MySQL dump file (see also <xref linkend="phpMyAdmin-navigation-bar-SQL">).</para></sect2>
</sect1>
<sect1 id="phpmyadmin"><title>How to install <application>PHP-Nuke</application> through phpMyAdmin</title><para>To be able to create a database,<indexterm><primary>base</primary></indexterm> you must be able to administer it. A perfect instrument for doing this via a browser is phpMyAdmin.<indexterm><primary>Admin</primary></indexterm></para><sect2 id="whatis-phpmyadmin"><title>What Is PHPMyadmin</title><para><ulink url="http://www.phpmyadmin.net/">PHPMyAdmin</ulink> is a visual system for the management of a <ulink url="http://www.mysql.org">MySQL</ulink> database (see <xref linkend="fig-phpmyadmin-start">). It is written in <ulink url="http://www.php.net">PHP</ulink> and serves to display the contents of the databases on the server (or client) on which MySQL is installed. Through this interface you can create new databases,<indexterm><primary>databases</primary></indexterm> modify existing ones and modify the contents of single fields.</para></sect2>
<sect2 id="install-phpMyAdmin"><title>How to install phpMyAdmin</title><para>Local installation under <productname>Windows</productname> is very simple: you only need to extract<indexterm><primary>extract</primary></indexterm> the files from the archive you downloaded from the <ulink url="http://www.phpbb.com">official phpBB site</ulink> and point your browser to the address <ulink url="http://localhost/phpmyadmin">http://localhost/phpmyadmin</ulink>. You will then see a screen as in <xref linkend="fig-phpmyadmin-start">.</para><para>
<figure id="fig-phpmyadmin-start">
<title>
PHPMyAdmin start screen.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1009;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1009;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1009;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1009;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>PHPMyAdmin start screen.</phrase>
</textobject>
<caption>
<para>PHPMyAdmin start screen.</para>
</caption>
</mediaobject>
</figure>
</para><para>If you are working locally, don't worry about any warnings you might get. In case you have to install phpMyAdmin on your server,<indexterm><primary>server</primary></indexterm> e.g. when your ISP does not offer a preinstalled administration panel for the database,<indexterm><primary>base</primary></indexterm> you must configure the config.inc.php file that comes with it:</para><para>Supposing that your data are:</para><itemizedlist><listitem><para>IP of the database server:<indexterm><primary>server</primary></indexterm> 156.123.22.34</para></listitem><listitem><para>User: Pippo<indexterm><primary>Pippo</primary></indexterm></para></listitem><listitem><para>Password: Topolino<indexterm><primary>Topolino</primary></indexterm></para></listitem><listitem><para>Database name: Minnie<indexterm><primary>Minnie</primary></indexterm></para></listitem></itemizedlist><para>then the necessary entries in config.<indexterm><primary>config</primary></indexterm>inc.php look like this:</para><screen><![CDATA[$cfgServers[1]["host"] = "156.123.22.34"; // MySQL hostname
]]><![CDATA[$cfgServers[1]["port"] = ""; // MySQL port - leave blank for default port
]]><![CDATA[$cfgServers[1]["adv_auth"] = false; // Use advanced authentication?
]]><![CDATA[$cfgServers[1]["stduser"] = ""; // MySQL standard user (only needed with advanced auth)
]]><![CDATA[$cfgServers[1]["stdpass"] = ""; // MySQL standard password (only needed with advanced auth)
]]><![CDATA[$cfgServers[1]["user"] = "Pippo"; // MySQL user (only needed with basic auth)
]]><![CDATA[$cfgServers[1]["password"] = "Topolino"; // MySQL password (only needed with basic auth)
]]><![CDATA[$cfgServers[1]["only_db"] = "Minnie"; // If set to a db-name, only this db is accessible
]]><![CDATA[$cfgServers[1]["verbose"] = ""; // Verbose name for this host - leave blank to show the hostname
]]><![CDATA[$cfgServers[1]["bookmarkdb"] = ""; // Bookmark db - leave blank for no bookmark support
]]><![CDATA[$cfgServers[1]["bookmarktable"] = ""; // Bookmark table - leave blank for no bookmark support
]]><![CDATA[
]]></screen><para>In the config.<indexterm><primary>config</primary></indexterm>inc.php you will find more configuration parameters that are repeated. They serve to manage DBs in various hosts with the same interface.<indexterm><primary>interface</primary></indexterm></para></sect2>
</sect1>
<sect1 id="phpmyadmin2"><title>phpMyAdmin: How to administer MySQL via Web</title><para>Once you have opened your phpMyAdmin (to do this, if you are working locally, you would have to open <ulink url="http://localhost/phpmyadmin">http://localhost/phpmyadmin</ulink> with your browser), you will get a screen that offers you the possibilities of </para><itemizedlist><listitem><para>Select a database through a drop-down list.</para></listitem><listitem><para>Create a new database<indexterm><primary>base</primary></indexterm></para></listitem></itemizedlist><para>as in <xref linkend="fig-phpmyadmin-select-database">.</para><para>
<figure id="fig-phpmyadmin-select-database">
<title>
phpMyAdmin: Select database.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1010;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1010;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1010;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1010;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>phpMyAdmin: Select database.</phrase>
</textobject>
<caption>
<para>phpMyAdmin: Select database.</para>
</caption>
</mediaobject>
</figure>
</para><para>Once you have chosen the desired operation,<indexterm><primary>operation</primary></indexterm> you arrive at the administration interface of your phpMyAdmin.<indexterm><primary>Admin</primary></indexterm> Newer versions contain a navigation bar, located at the top (<xref linkend="fig-phpmyadmin-navigation-bar">), offering the following options: </para><itemizedlist><listitem><para>Structure: See the database structure.<indexterm><primary>structure</primary></indexterm></para></listitem><listitem><para>SQL:<indexterm><primary>SQL</primary></indexterm> Execute SQL operations (e.g. load an existing database).</para></listitem><listitem><para>Export: Make a backup of the database.<indexterm><primary>base</primary></indexterm></para></listitem><listitem><para>Search: Search for data.<indexterm><primary>data</primary></indexterm></para></listitem><listitem><para>Query:<indexterm><primary>Query</primary></indexterm> Display the structure of an SQL query (useful for programmers).</para></listitem><listitem><para>Drop: Delete a database (be careful!).</para></listitem></itemizedlist><para>
<figure id="fig-phpmyadmin-navigation-bar">
<title>
phpMyAdmin: Navigation bar.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1011;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1011;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1011;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1011;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>phpMyAdmin: Navigation bar.</phrase>
</textobject>
<caption>
<para>phpMyAdmin: Navigation bar.</para>
</caption>
</mediaobject>
</figure>
</para><para>As far as we are concerned here, we only need to explain the first 3 items:</para><sect2 id="phpMyAdmin-navigation-bar-Structure"><title>phpMyAdmin navigation bar: Structure</title><para>&ldquo;Structure&rdquo; presents a list of the available tables in the database,<indexterm><primary>base</primary></indexterm> with the follwing accompanying options:</para><itemizedlist><listitem><para>Browse:<indexterm><primary>Browse</primary></indexterm> shows the content of the table.</para></listitem><listitem><para>Select: is used to make SQL queries to the table.</para></listitem><listitem><para>Insert: is used to insert new data into the table.</para></listitem><listitem><para>Properties: displays the structure of the table, ie. its fields, their type, length etc.</para></listitem><listitem><para>Drop: deletes the table (be careful!).</para></listitem><listitem><para>Empty: empties the content of the table, but does not delete the table itself, it leaves it empty (be careful again!).</para></listitem></itemizedlist><para>The most frequently asked questions in this context are:</para><variablelist><varlistentry><term>How&nbsp;do&nbsp;I&nbsp;delete&nbsp;a&nbsp;single&nbsp;record&nbsp;of&nbsp;the&nbsp;table?
</term><listitem><para>Select the table, click on &ldquo;Browse<indexterm><primary>Browse</primary></indexterm>&rdquo; and select &ldquo;Delete&rdquo; for the record in question.</para></listitem></varlistentry><varlistentry><term>If&nbsp;the&nbsp;password&nbsp;is&nbsp;stored&nbsp;encrypted&nbsp;with&nbsp;MD5,&nbsp;how&nbsp;do&nbsp;I&nbsp;change&nbsp;it?
</term><listitem><para>Select the table, click on &ldquo;Browse<indexterm><primary>Browse</primary></indexterm>&rdquo;, then on &ldquo;Edit<indexterm><primary>Edit</primary></indexterm>&rdquo; and enter, in clear text, the desired password.<indexterm><primary>password</primary></indexterm> Select from the drop-down &ldquo;Function&rdquo; menu besides the field the desired function,<indexterm><primary>function</primary></indexterm> in our case &ldquo;MD5<indexterm><primary>MD5</primary></indexterm>&rdquo; (see <xref linkend="fig-phpmyadmin-field-functions">). See also <xref linkend="administrator-password-lost">.</para></listitem></varlistentry></variablelist><para>
<figure id="fig-phpmyadmin-field-functions">
<title>
phpMyAdmin: field functions.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1012;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1012;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1012;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1012;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>phpMyAdmin: field functions.</phrase>
</textobject>
<caption>
<para>phpMyAdmin: field functions.</para>
</caption>
</mediaobject>
</figure>
</para></sect2>
<sect2 id="phpMyAdmin-navigation-bar-SQL"><title>phpMyAdmin navigation bar: SQL</title><para>&ldquo;SQL<indexterm><primary>SQL</primary></indexterm>&rdquo; serves the purpose of &ldquo;loading&rdquo; whole datasets or already existing databases with one action. The datasets (or the database) are presumed to be already available in a MySQL &ldquo;dump file&rdquo;. This is a text file containing all the necessary SQL queries that must be sent to the database server,<indexterm><primary>server</primary></indexterm> in order for the datasets or database to be created. An example of such a dump file is the nuke.sql file that comes with <application>PHP-Nuke</application> and contains all the database instructions for the tables to be created during installation (see <xref linkend="install-db">).</para><para>The use of this function is very simple: just search your system for the dump file you want to load,<indexterm><primary>load</primary></indexterm> by hitting the &ldquo;Browse<indexterm><primary>Browse</primary></indexterm>&rdquo; button (<xref linkend="fig-phpmyadmin-SQL">). MySQL dump files usually come with the &ldquo;.sql&rdquo; ending, but &ldquo;.sql.php&rdquo;, &ldquo;.txt&rdquo; or even &ldquo;.php&rdquo; are also in use. Whether the file is a MySQL dump file or not, can only be told by inspection: open it with a <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=122">decent text editor</ulink> (see <xref linkend="editing-PHP-Nuke-files">) and if the first lines look like </para><screen><![CDATA[# MySQL dump 6.6
]]><![CDATA[#
]]><![CDATA[...
]]><![CDATA[#
]]><![CDATA[# Table structure for table 'xxxxx'
]]><![CDATA[#
]]><![CDATA[CREATE TABLE xxxxx ...
]]><![CDATA[...
]]><![CDATA[#
]]><![CDATA[# Dumping data for table 'xxxxx'
]]><![CDATA[#
]]><![CDATA[INSERT INTO xxxxx ...
]]></screen><para>i.e. if it contains CREATE and/or INSERT SQL statements,<indexterm><primary>statements</primary></indexterm> then it is a dump file (see also <xref linkend="phpMyAdmin-navigation-bar-Export">).</para><para>This function is useful when you want to create whole databases and fill them with data in one step, but it is also very useful when you want to add data to an existing database.<indexterm><primary>base</primary></indexterm> However, this does not mean that it will always succeed: especially if the dump files are very large, this operation my exceed the <acronym>PHP</acronym> <acronym>CPU</acronym> limit (usually set to 30 sec. by the ISPs). (see, for example, <xref linkend="backup-mysql-using-browser">)</para><para>
<figure id="fig-phpmyadmin-SQL">
<title>
phpMyAdmin: SQL function.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1013;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1013;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1013;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1013;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>phpMyAdmin: SQL function.</phrase>
</textobject>
<caption>
<para>phpMyAdmin: SQL function.</para>
</caption>
</mediaobject>
</figure>
</para><caution>
<title>Beware of long .sql files!</title>
<para>
You can of course use phpMyAdmin to comfortably import any MySQL dump file, i.e. from a previous backup of an existing installation with thousands of forums posts. In this case, the import may take longer than the limit on the execution time of <acronym>PHP</acronym> scripts that most ISPs set (usually 30 sec.). You will end up with a half-filled database!
</para>
<para>
In this case, either cut the file up into smaller chucks and use phpMyAdmin to load the smaller files, or insert the text piecewise for execution in the text area field of phpMyAdmin that is there for this purpose, or, as a last resort, do it from the command line, as shown in <xref linkend="database-creation">.
</para>
<para>
See also <ulink url="http://forums.devshed.com/archive/4/2001/07/2/17971">how to import a '.sql' (>3M) file to mysql database with phpmyadmin?</ulink>, <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=16590">Importing .sql files into an existing database in phpmyadmin</ulink>.
</para>
</caution>
</sect2>
<sect2 id="phpMyAdmin-navigation-bar-Export"><title>phpMyAdmin navigation bar: Export</title><para>
<figure id="fig-phpmyadmin-database-dump">
<title>
phpMyAdmin: database dump.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1014;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1014;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1014;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1014;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>phpMyAdmin: database dump.</phrase>
</textobject>
<caption>
<para>phpMyAdmin: database dump.</para>
</caption>
</mediaobject>
</figure>
</para><para>The &ldquo;Export&rdquo; function is useful for obtaining backups of our database (we recall that this is also possible to do from the administration panel of PHP-Nuke, see <xref linkend="administration-functions">). The management console we get for this function is quite detailed (<xref linkend="fig-phpmyadmin-database-dump">):</para><para>In the central area, we have a list of the database tables,<indexterm><primary>tables</primary></indexterm> while to the right we have the backup options:</para><itemizedlist><listitem><para>Structure only: backs up the structure of the database (tables,<indexterm><primary>tables</primary></indexterm> their fields and their properties), but not the data it contains (i.e. the tables are left empty).</para></listitem><listitem><para>Structure and data:<indexterm><primary>data</primary></indexterm> will save not only the structure, as above, but the data in the tables as well.</para></listitem><listitem><para>Data only: will save only the data,<indexterm><primary>data</primary></indexterm> but not the structure.</para></listitem><listitem><para>XML: saves the database in an XML format.<indexterm><primary>format</primary></indexterm></para></listitem></itemizedlist><para>The options that appear in the lower part of the screen have to do with the extra features the created backup file should have:</para><itemizedlist><listitem><para>Add 'Drop Table': Prepends an instruction to destroy any existing table with that name to the instructions that create that table. For example, if we already have a table &ldquo;nuke_authors<indexterm><primary>nuke_authors</primary></indexterm>&rdquo; in our database,<indexterm><primary>base</primary></indexterm> this option will take care of removing it, before it loads the structure and/or data for a table with the same name. Otherwise, attempting to import a file that contains structure and/or data<indexterm><primary>data</primary></indexterm> for nuke_authors will result in an error, since the table will already exist. You should check this option if you are reinstalling <application>PHP-Nuke</application> over a previous unsuccessful instalation and you think you might already have some tables<indexterm><primary>tables</primary></indexterm> there.</para></listitem><listitem><para>Save as file: will save the backup as a file (which will be compressed accordingly, with either ZIP or GZIP,<indexterm><primary>GZIP</primary></indexterm> if the &ldquo;zipped<indexterm><primary>zipped</primary></indexterm>&rdquo; or &ldquo;gzipped<indexterm><primary>zipped</primary></indexterm>&rdquo; boxes are checked - other versions of phpMyAdmin may only offer a &ldquo;bzip<indexterm><primary>zip</primary></indexterm>&rdquo; compression).</para></listitem></itemizedlist><para>If we don't select any table from the table list, phpMyAdmin will deduce that we want to save all tables.<indexterm><primary>tables</primary></indexterm> In case you want to select only some of them, just click on the ones you want with the left mouse button, keeping the CTRL button pressed.</para><para>To export a database from the command-line,<indexterm><primary>command-line</primary></indexterm> without the use of the graphical tool of phpMyAdmin,<indexterm><primary>Admin</primary></indexterm> you just do:</para><screen><![CDATA[mysqldump -u dbuser -h dbhost -p dbname > dbdump.sql
]]></screen><para>where dbuser,<indexterm><primary>dbuser</primary></indexterm> dbhost and dbname are the database user, host and name respectively, exactly as entered in config.<indexterm><primary>config</primary></indexterm>php (<xref linkend="config-php-file">).</para></sect2>
<sect2 id="phpMyAdmin-other-commands"><title>phpMyAdmin: other commands</title><para>Yet another couple of instructions: In order to see the structure of a table, you only need to click on the one that is marked in the left bar and you will see all its fields and modification options appear in the central part (<xref linkend="fig-forum-topics">).</para><para>
<figure id="fig-forum-topics">
<title>
phpMyAdmin: table forum_topics.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1015;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1015;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1015;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1015;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>phpMyAdmin: table forum_topics.</phrase>
</textobject>
<caption>
<para>phpMyAdmin: table forum_topics.</para>
</caption>
</mediaobject>
</figure>
</para><caution>
<title>
ATTENTION!
</title>
<para>
The DROP command eliminates all the contents of the DB, the table or the single field, use it with caution.
</para>
</caution>
<para>To learn more about the possibilities that phpMyAdmin offers you in administering your databases,<indexterm><primary>databases</primary></indexterm> see <ulink url="http://www.devshed.com/Server_Side/PHP/Doing_More_phpMyAdmin/page1.html">Doing More With phpMyAdmin (Part 1)</ulink> and <ulink url="http://www.devshed.com/Server_Side/PHP/Doing_More_phpMyAdmin_part2/page1.html">Doing More With phpMyAdmin (Part 2)</ulink>. The first part explains how to obtain the software, install and configure it for secure access,<indexterm><primary>access</primary></indexterm> and use it for tasks such as managing multiple servers, manipulating user privileges,<indexterm><primary>privileges</primary></indexterm> viewing reports on server activity, and exporting MySQL records into different formats.<indexterm><primary>formats</primary></indexterm> The second part explains the more advanced aspects of the application,<indexterm><primary>application</primary></indexterm> including using it for transformations,<indexterm><primary>ations</primary></indexterm> maintaining a history of all the SQL queries executed in the phpMyAdmin session,<indexterm><primary>session</primary></indexterm> defining relations between tables to create JOINs automatically, creating E-R diagrams in PDF format,<indexterm><primary>format</primary></indexterm> and bookmarking important queries for future reference.</para></sect2>
<sect2 id="install-db"><title>How to install the DB of <application>PHP-Nuke</application> with PHPMyadmin</title><para>Create a database that will contain the <application>PHP-Nuke</application> tables (see <xref linkend="fig-phpmyadmin-create-database">). The name of the database should be the same name as the one you entered in config.<indexterm><primary>config</primary></indexterm>php (see <xref linkend="config-php-file">). </para><para>
<figure id="fig-phpmyadmin-create-database">
<title>
phpMyAdmin: Create database.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1016;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1016;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1016;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1016;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>phpMyAdmin: Create database.</phrase>
</textobject>
<caption>
<para>phpMyAdmin: Create database.</para>
</caption>
</mediaobject>
</figure>
</para><para>To populate the database,<indexterm><primary>base</primary></indexterm> you have to import the nuke.sql file, exactly as we showed in <xref linkend="phpMyAdmin-navigation-bar-SQL"> for general database dump files. Clicking on the left bar, depending on the database you selected, you will see a list menu coming up, showing the structure of the database (and, on the same time, the central page will show the enlarged structure of the database), with a series of options, all of them in the bottom of the page (see <xref linkend="fig-phpmyadmin-table-structure">). It is these options we are interested in when installing <application>PHP-Nuke</application>.</para><para>
<figure id="fig-phpmyadmin-table-structure">
<title>
phpMyAdmin: table structure and selection.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1017;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1017;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1017;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1017;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>phpMyAdmin: table structure and selection.</phrase>
</textobject>
<caption>
<para>phpMyAdmin: table structure and selection.</para>
</caption>
</mediaobject>
</figure>
</para><para>What you have to do now, is to click on &ldquo;browse&rdquo; and go search for the .sql file that contains the instructions that build the structure of the <application>PHP-Nuke</application> database (see <xref linkend="fig-phpmyadmin-sql-query">). Once found, it suffices to click on &ldquo;Go&rdquo; and the database will be installed. Of course, if there are errors, they will be reported at the end of the installation procedure.<indexterm><primary>procedure</primary></indexterm> And of course, the same holds for the message &ldquo;operation succeeded&rdquo;.</para><caution>
<title>Don't delete the whole database on the ISP!</title>
<para>
If you have bought some hosting space on your ISP's servers, you may not be able to create databases at your will, but be constrained to use only the one that your ISP created for you. In this case, you can create, delete and modify its tables and their contents, but not the database itself! Don't drop the whole database, as you may not be allowed to recreate it!
</para>
</caution>
<para>
<figure id="fig-phpmyadmin-sql-query">
<title>
phpMyAdmin: SQL query.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1018;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1018;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1018;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1018;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>phpMyAdmin: SQL query.</phrase>
</textobject>
<caption>
<para>phpMyAdmin: SQL query.</para>
</caption>
</mediaobject>
</figure>
</para><para>You can verify that the tables were populated with data by browsing their contents (<xref linkend="fig-phpmyadmin-table-data">) - click on the small icons besides their names in the left frame for this (if you click on their names, you will only see their structure). </para><para>
<figure id="fig-phpmyadmin-table-data">
<title>
phpMyAdmin: table data.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1019;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1019;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1019;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1019;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>phpMyAdmin: table data.</phrase>
</textobject>
<caption>
<para>phpMyAdmin: table data.</para>
</caption>
</mediaobject>
</figure>
</para><para>Other options of PHPMyAdmin that are not relative to the installation<indexterm><primary>installation</primary></indexterm> of PHP-Nuke, but still useful for the administration of the database,<indexterm><primary>base</primary></indexterm> can be found in <xref linkend="phpmyadmin">.</para></sect2>
</sect1>
<sect1 id="install-PHP-Nuke-nukesql"><title>How to install <application>PHP-Nuke</application> using nukesql.php</title><para>If fiddling with the database from the MySQL command line does not make you feel comfortable, you can use one of the <ulink url="http://www.nukeresources.com/modules.php?name=Downloads&amp;d_op=search&amp;query=nukesql">Web Installers for PHP-Nuke</ulink> available for your version, in the form of the nukesql.php script. This file will install all required database tables for a fresh installation<indexterm><primary>installation</primary></indexterm> of <application>PHP-Nuke</application>. It works a follows:</para><para>Simply enter your database login information in config.<indexterm><primary>config</primary></indexterm>php (see <xref linkend="config-php-file">), upload all <application>PHP-Nuke</application> files (<xref linkend="upload">), then upload this file to PHP-Nuke's root directory and point your browser to it (e.g. http://yoursite.com/nukesql.php).</para><para>nukesql.php proceeds in an interactive way to populate the database tables<indexterm><primary>tables</primary></indexterm> and test your settings in config.php.<indexterm><primary>config.php</primary></indexterm></para><para>Some of its features:<indexterm><primary>features</primary></indexterm></para><itemizedlist><listitem><para>Checks that you are not using the default $sitekey (<xref linkend="fig-analyze-warning-sitekey">).</para></listitem><listitem><para>Lists existing database tables if any.</para></listitem><listitem><para>Installs tables on a empty database.<indexterm><primary>base</primary></indexterm></para></listitem><listitem><para>Replaces existing tables with new ones.</para></listitem><listitem><para>Creates duplicate tables for a second nuke site using one database by using a different prefix in config.<indexterm><primary>config</primary></indexterm>php (see also <xref linkend="more-than-one-php-nuke-sites">).</para></listitem><listitem><para>Will help you troubleshoot installation by testing connection to the MySQL<indexterm><primary>MySQL</primary></indexterm> server and selection of database (see also <xref linkend="test-scripts">).</para></listitem></itemizedlist></sect1>
<sect1 id="install-PHP-Nuke-locally"><title>How to install <application>PHP-Nuke</application> locally</title><para>A <application>PHP-Nuke</application> installation on your own computer will give you the opportunity to test the whole spectrum of functionalities offered, as if you were online and your system were hosted in your ISP.<indexterm><primary>ISP</primary></indexterm> But in order to start working on <application>PHP-Nuke</application> locally, you must have a web server installed on your box. In this section we will cover the necessary steps towards a working <application>PHP-Nuke</application> environment (Apache + <acronym>PHP</acronym> + MySQL ) under <productname>Windows</productname> and <productname>Linux</productname>.<indexterm><primary>Linux</primary></indexterm></para><para>For Windows,<indexterm><primary>Windows</primary></indexterm> there are various packages you can choose from - they will install Apache, <acronym>PHP</acronym> and even MySQL for you and will provide a ready-to-use<indexterm><primary>ready-to-use</primary></indexterm> environment for the installation of <application>PHP-Nuke</application>. Among them, there are easyPHP (<xref linkend="easyPHP">), XAMPP (<xref linkend="XAMPP">) and Apache2Triad (<xref linkend="Apache2Triad">).</para><sect2 id="easyPHP"><title>easyPHP</title><para>After the <ulink url="http://www.easyphp.org/telechargements.php3">download of easyPHP</ulink> (version 1.6 or later), istallation is really easy: just click the setup<indexterm><primary>setup</primary></indexterm> icon to start it. You will be asked a few questions in the processes and that's all. The first screen is a welcome message and you only have to click on &ldquo;next&rdquo; (&ldquo;suivant&rdquo;). You will then be presented with screens like licence etc. and you can continue clicking on &ldquo;next&rdquo; (&ldquo;suivant&rdquo;), until you reach the screen that asks you where you want to install easyPHP<indexterm><primary>easyPHP</primary></indexterm> (<xref linkend="fig-easyphp">), in which case you just choose the right path (if you have doubts about the right path, you can leave it to the default just as well).</para><para>
<figure id="fig-easyphp">
<title>
easyPHP: Installation screen.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1020;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1020;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1020;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1020;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>easyPHP: Installation screen.</phrase>
</textobject>
<caption>
<para>easyPHP: Installation screen.</para>
</caption>
</mediaobject>
</figure>
</para><para>Continue clicking on &ldquo;suivant&rdquo; until the end of the installation,<indexterm><primary>installation</primary></indexterm> when you have to click on &ldquo;terminer&rdquo; to end it. easyPHP is now installed.</para><para>But where should you install <application>PHP-Nuke</application> in a system with easyPHP installed? Suppose you installed easyPHP in a folder like c:\easyphp.<indexterm><primary>easyphp</primary></indexterm> Open that folder and you will find various subdirectories.<indexterm><primary>subdirectories</primary></indexterm> The one that is important is www. It is under the www folder that the local copy of Apache will expect the files to process - and it is exactly there where you should install PHP-NukeI in the c:\easyphp<indexterm><primary>easyphp</primary></indexterm>\www folder.</para><para>We must still explain a couple of elements of easyPHP's functioning. Once you start the easyPHP application,<indexterm><primary>application</primary></indexterm> you will find an icon in the bottom bar, to the right of your screen,<indexterm><primary>screen</primary></indexterm> that resembles an &ldquo;e&rdquo; with a small red point (<xref linkend="fig-easyphp2">). If the red point is lighting, the server is active, if it is dimmed out, the server is shut down.</para><para>
<figure id="fig-easyphp2">
<title>
easyPHP icon in the bottom bar.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1021;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1021;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1021;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1021;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>easyPHP icon in the bottom bar.</phrase>
</textobject>
<caption>
<para>easyPHP icon in the bottom bar.</para>
</caption>
</mediaobject>
</figure>
</para><para>To administrate easyPHP,<indexterm><primary>easyPHP</primary></indexterm> you only have to click on that black &ldquo;e&rdquo;. A right click with the mouse will offer a menu with all commands available for the server administration,<indexterm><primary>administration</primary></indexterm> a double click with the left mouse button will instead offer an information screen.<indexterm><primary>screen</primary></indexterm></para><sect3 id="easyPHP-check-successful-installation"><title>How to check a successful installation</title><para>To make sure that Apache and <acronym>PHP</acronym> have been installed correctly on our system,<indexterm><primary>system</primary></indexterm> we will use the phpinfo() function of PHP,<indexterm><primary>PHP</primary></indexterm> which asks the server to give information about the <acronym>PHP</acronym> configuration.<indexterm><primary>configuration</primary></indexterm> If we get a screen like the one of <xref linkend="fig-phpinfo-php-Windows">, then everything is working correctly.</para><para>
<figure id="fig-phpinfo-php-Windows">
<title>
phpinfo: <acronym>PHP</acronym> screen for a <productname>Windows</productname> system.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1022;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1022;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1022;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1022;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>phpinfo: <acronym>PHP</acronym> screen for a <productname>Windows</productname> system.</phrase>
</textobject>
<caption>
<para>phpinfo: <acronym>PHP</acronym> screen for a <productname>Windows</productname> system.</para>
</caption>
</mediaobject>
</figure>
</para><para>To construct a file that uses the phpinfo() function,<indexterm><primary>function</primary></indexterm> you can either use the text.php script of <xref linkend="test-php">, or, even more simply, create a text file (with a <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=122">decent text editor</ulink>, see also <xref linkend="editing-PHP-Nuke-files">) that contains only the line</para><screen><![CDATA[<? phpinfo(); ?>
]]></screen><para>Save the file under the name, say, info.<indexterm><primary>info</primary></indexterm>php and move it to the www folder of the easyPHP directory (we talked about it above). Then enter the URL<indexterm><primary>URL</primary></indexterm></para><screen><![CDATA[http://localhost/info.php
]]></screen><para>in the address bar of your browser and you should get (among other information) the screen of <xref linkend="fig-phpinfo-php-Windows">.</para></sect3>
</sect2>
<sect2 id="XAMPP"><title>XAMPP</title><para><ulink url="http://www.apachefriends.org/xampp-en.html">XAMPP</ulink> is an easy to install Apache distribution containing MySQL,<indexterm><primary>MySQL</primary></indexterm> <acronym>PHP</acronym> and <application>Perl</application>. XAMPP is really very easy to install and to use - just download,<indexterm><primary>download</primary></indexterm> extract and start.</para><para>The distribution for <productname>Linux</productname> system (tested for SuSE, RedHat,<indexterm><primary>RedHat</primary></indexterm> <productname>Mandrake</productname> and Debian) contains: Apache, MySQL, <acronym>PHP</acronym> &amp; PEAR,<indexterm><primary>PEAR</primary></indexterm> Perl, ProFTPD, phpMyAdmin, OpenSSL, GD, Freetype2, libjpeg, libpng, gdbm, zlib,<indexterm><primary>zlib</primary></indexterm> expat, Sablotron, libxml, Ming, Webalizer, pdf class, ncurses, mod_perl,<indexterm><primary>mod_perl</primary></indexterm> FreeTDS, gettext, mcrypt,<indexterm><primary>mcrypt</primary></indexterm> mhash, Turck MMCache, SQLite and IMAP C-Client.</para><para>The distribution for <productname>Windows</productname> 98, NT, 2000 and XP contains: Apache, MySQL,<indexterm><primary>MySQL</primary></indexterm> <acronym>PHP</acronym> + PEAR, Perl, mod_php,<indexterm><primary>mod_php</primary></indexterm> mod_perl, mod_ssl, OpenSSL, phpMyAdmin, Webalizer, Mercury Mail Transport System for Win32 and NetWare Systems v3.32, JpGraph,<indexterm><primary>JpGraph</primary></indexterm> FileZilla FTP Server, mcrypt, Turck MMCache, SQLite, and WEB-DAV + mod_auth_mys<indexterm><primary>mod_auth_mys</primary></indexterm>ql. The versions of the programs included in the latest version for Windows<indexterm><primary>Windows</primary></indexterm> are:</para><itemizedlist><listitem><para>Apache 2.0.48 </para></listitem><listitem><para>MySQL 4.0.16</para></listitem><listitem><para>PHP 4.3.4 </para></listitem><listitem><para>Openssl 0.9.7c</para></listitem><listitem><para>SQLite 2.8.6 </para></listitem><listitem><para>mod_php 4.3.4 + mod_perl 1.99_10 + mod_ssl 2.0.48</para></listitem></itemizedlist><para>To install XAMPP you only need to download and extract XAMPP,<indexterm><primary>XAMPP</primary></indexterm> that's all. There are no changes to the <productname>Windows</productname> registry and it's not necessary to edit any configuration files. It couldn't be easier!</para><para>To check that XAMPP is working some sample programs are included, there is a small CD collection program (written in <acronym>PHP</acronym> using MySQL) and a small guest book software (written in Perl) and several other utilities.</para><para>If you decide that XAMPP isn't needed any more just delete the XAMPP directory and it's completely removed from your system.<indexterm><primary>system</primary></indexterm> </para><important>
<title>On the press: Call for donations</title>
<para>
On December 19, 2003, someone applied to the German Patent and Trademark Office for the rights to the "XAMPP" name. This person was not one of the XAMPP developers, but someone totally unknown to them.
</para>
<para>
The trademark application is a danger for the project's future, since the applicant could - if no legal measures are taken - forbid that the XAMPP developers use that name for their software or do business taking advantage of the name's popularity.
</para>
<para>
The XAMPP developers call on the project's website for donations to help counter this threat with legal means. Whether you are a new XAMPP user, a friend of Apache Friends, or just someone who would like to help, please take the time and <ulink url="http://www.apachefriends.org/genugistgenug.html">make a donation to the XAMPP project</ulink>.
</para>
</important>
</sect2>
<sect2 id="Apache2Triad"><title>Apache2Triad</title><para><ulink url="http://www.hotscripts.com/Detailed/23555.html">Apache2Triad</ulink> offers the following goodies,<indexterm><primary>goodies</primary></indexterm> according to the Description:</para><blockquote><para>Apache 2.0.47 , MySQL 4.0.13 , OpenSSL 0.9.7b <acronym>PHP</acronym> 4.3.3 , <application>Perl</application> 5.8.0 , Tcl 8.4.2 , Python<indexterm><primary>Python</primary></indexterm> 2.2.2 plus <application>PHP-Nuke</application> 6.8 , PHPmyadmin 2.5.2 , AWStats 5.7 plus Stunnel 4.04 , SSLCert<indexterm><primary>SSLCert</primary></indexterm> 1.0 plus Xmail 1.1.6 and SlimFTPd 3.13 plus UebiMiau 2.7.2 and PHPXmail 0.33 all configured and easy to install and easy to customize as it has the cleanest layout and structure there is and is updated for every new release of the software it contains plus The Apache2triad Control Pannel suite of tools plus Full documentations plus Unparalelled Installer.</para></blockquote><para>The homepage of the program is <ulink url="http://apache2triad.org/">Apache2Triad</ulink>. Apache2Triad is not free for commercial usage: if your company wants to use Apache2Triad you must purchase it for 15$, which is certainly worth the money if you only think at the frustration it saves you by installing all the above packages for you.</para></sect2>
<sect2 id="Mandrake-Linux-Apache-PHP-MySQL"><title>Apache, <acronym>PHP</acronym> and MySQL on <productname>Mandrake</productname> Linux</title><para>We will describe how to get a functioning, local installation of the Apache-PHP-MySQL trio on a <productname>Linux</productname> system - we chose <productname>Mandrake</productname> <productname>Linux</productname> for this purpose, but the process is similar with other distributions. We will use visual tools for our purposes, making the assumption that, whoever is capable of compiling the binaries from the source code himself, will not need our guidance.</para><para>
<figure id="fig-apache-package">
<title>
RPMdrake: selecting the Apache package(s) for installation.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1023;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1023;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1023;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1023;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>RPMdrake: selecting the Apache package(s) for installation.</phrase>
</textobject>
<caption>
<para>RPMdrake: selecting the Apache package(s) for installation.</para>
</caption>
</mediaobject>
</figure>
</para><para>The most simple thing to do to get Apache,<indexterm><primary>Apache</primary></indexterm> <acronym>PHP</acronym> and MySQL installed under Linux,<indexterm><primary>Linux</primary></indexterm> is to install the appropriate packages from the CD. For this, we will use the software application tool called RPMdrake;<indexterm><primary>RPMdrake</primary></indexterm> upon execution, it will ask for the root password;<indexterm><primary>password</primary></indexterm> after we enter it, we will be presented a screen that asks us what we want to install. We enter &ldquo;Apache<indexterm><primary>Apache</primary></indexterm>&rdquo; in the aproppriate field and in the sequence we choose the main Apache<indexterm><primary>Apache</primary></indexterm> package (<xref linkend="fig-apache-package">). RPMdrake will ask us if we also want to install the packages of the &ldquo;dependencies<indexterm><primary>dependencies</primary></indexterm>&rdquo; (i.e. packages which the main package we selected depends on). It is important to answer with &ldquo;yes&rdquo; here.</para><para>We then click on &ldquo;install&rdquo; and we are asked to insert the CD (or the CDs) containing the <acronym>RPM</acronym> packages.<indexterm><primary>packages</primary></indexterm> Once Apache has been installed, we open the <productname>Mandrake</productname> Control Center and click on &ldquo;Start&rdquo; for the httpd service (<xref linkend="fig-mandrake-control-center">).</para><para>
<figure id="fig-mandrake-control-center">
<title>
<productname>Mandrake</productname> Control Center.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1024;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1024;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1024;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1024;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Mandrake Control Center.</phrase>
</textobject>
<caption>
<para>Mandrake Control Center.</para>
</caption>
</mediaobject>
</figure>
</para><para>The last control step is to open our browser and instruct it to open http://localhost/. If the browser's response is Apache's Welcome Page, we are done.</para><para>We have to repeat the above operations in the same identical way for the <acronym>PHP</acronym> and MySQL packages.<indexterm><primary>packages</primary></indexterm> In order to make the MySQL database service available, we have again to go to <productname>Mandrake</productname> Control Center and click on &ldquo;Start&rdquo; for the mysql service - <acronym>PHP</acronym> does not need this step, it is available immediately after installation.<indexterm><primary>installation</primary></indexterm></para><para>But where is the folder for the HTML files and our PHP-Nuke? It turns out that this is under /var/www/html and we should use phpMyAdmin (<xref linkend="phpmyadmin">) to give this folder the permissions of 777 (for more on file permissions,<indexterm><primary>permissions</primary></indexterm> see <xref linkend="permissions">). This way all users will be able to add, modify and delete files there, not only root.<indexterm><primary>root</primary></indexterm></para><para>To verify that everything has gone well, we use the info.<indexterm><primary>info</primary></indexterm>php file of <xref linkend="easyPHP-check-successful-installation">. If we get a screen similar to that of <xref linkend="fig-phpinfo-php-Windows">, then everything is fine.</para></sect2>
<sect2 id="Red-Hat-Linux-Apache-PHP-MySQL"><title>Apache, <acronym>PHP</acronym> and MySQL on Red Hat Linux</title><para>For some obscure reason, Red Hat 8.0 does not connect the <acronym>PHP</acronym> package to that of MySQL and we have to resort to some tricks to make them work together. Thus, for Red Hat, you have to proceed as follows:</para><para>If Apache,<indexterm><primary>Apache</primary></indexterm> <acronym>PHP</acronym> and MySQL are not already installed, install the appropriate packages.<indexterm><primary>packages</primary></indexterm> For Red Hat 8.0, choose the &ldquo;Packages&rdquo; menu entry as shown in <xref linkend="fig-red-hat-menu-packages">.</para><para>
<figure id="fig-red-hat-menu-packages">
<title>
Red Hat Menu: Packages.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1025;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1025;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1025;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1025;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Red Hat Menu: Packages.</phrase>
</textobject>
<caption>
<para>Red Hat Menu: Packages.</para>
</caption>
</mediaobject>
</figure>
</para><para>Once you have entered the system (as root), you can choose the three necessary pieces (Apache,<indexterm><primary>Apache</primary></indexterm> <acronym>PHP</acronym> and MySQL):</para><itemizedlist><listitem><para>Apache is found under &ldquo;Web Server&rdquo;.</para></listitem><listitem><para>PHP is found under &ldquo;Web Server&rdquo;.</para></listitem><listitem><para>MySQL is found under &ldquo;SQL database Server&rdquo;.</para></listitem></itemizedlist><para>To see what is contained in each section, click on the &ldquo;Details&rdquo; link (<xref linkend="fig-red-hat-package-sections">).</para><para>
<figure id="fig-red-hat-package-sections">
<title>
Red Hat: Package Sections.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1026;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1026;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1026;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1026;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Red Hat: Package Sections.</phrase>
</textobject>
<caption>
<para>Red Hat: Package Sections.</para>
</caption>
</mediaobject>
</figure>
</para><para>After the selection of packages,<indexterm><primary>packages</primary></indexterm> you must click on &ldquo;Update<indexterm><primary>date</primary></indexterm>&rdquo; and Red Hat will go on to install them, after it has checked their dependencies.<indexterm><primary>dependencies</primary></indexterm> </para><para>Now, Apache,<indexterm><primary>Apache</primary></indexterm> <acronym>PHP</acronym> and MySQL are installed, but unfortunately, we are not yet done: we must ensure that <acronym>PHP</acronym> will talk to MySQL.<indexterm><primary>MySQL</primary></indexterm> To this end, we must do 2 things:</para><orderedlist><listitem><para><indexterm><primary>Enumerate</primary></indexterm>Edit the php.ini file, so that <acronym>PHP</acronym> supports also files that start with &ldquo;&lt;?&rdquo; - and not only those that start with &ldquo;&lt;?php&rdquo;.</para></listitem><listitem><para><indexterm><primary>Enumerate</primary></indexterm>Install the mysql.so file.</para></listitem></orderedlist><para>We recall that, in order to edit a system file, we must be root.<indexterm><primary>root</primary></indexterm> We can nevertheless do our edits without logging out first, if we do the following:</para><itemizedlist><listitem><para>Open a terminal window (System -&gt; Terminal)</para></listitem><listitem><para>Login as root (command &ldquo;su&rdquo;, then enter the password)</para></listitem><listitem><para>Start our preferred text editor (see <xref linkend="editing-PHP-Nuke-files">). The editor will start with root privileges,<indexterm><primary>privileges</primary></indexterm> so you can edit the php.ini file, usually located under /etc, and set the short_open_tag parameter<indexterm><primary>parameter</primary></indexterm> to ON:</para><screen><![CDATA[; Allow the <? tag. Otherwise, only <?php and <script> tags are recognized.
]]><![CDATA[short_open_tag = On
]]></screen></listitem><listitem><para>For your local experiments, it is comfortable to also set safe_mode to OFF and register_globals to ON (but see <xref linkend="security-measures"> for the security related point of view on this).</para></listitem><listitem><para>Save everything and you are done with operation 1 above.</para></listitem><listitem><para>Operation 2 is simple: just copy the mysql.so file brutally into /usr/lib/php4/. You should do this with root permissions.<indexterm><primary>permissions</primary></indexterm></para></listitem></itemizedlist><para>The only thing that remains now, is to restart the services.<indexterm><primary>services</primary></indexterm> We can do this from the command-line of a terminal window and also through a graphical tool. For the novice user, we will describe the graphical way - again, an advanced user will know how to do this from the command-line (see <ulink url="http://www.karakas-online.de/gnu-linux-tools-summary/">GNU/Linux Command-Line Tools Summary</ulink> for a compact summary of command-line tools in Linux).</para><para>
<figure id="fig-red-hat-service-configuration">
<title>
Red Hat: Service Configuration Panel.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1027;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1027;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1027;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1027;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Red Hat: Service Configuration Panel.</phrase>
</textobject>
<caption>
<para>Red Hat: Service Configuration Panel.</para>
</caption>
</mediaobject>
</figure>
</para><para>The activation or restart of the service we are interested in takes place by selecting the appropriate entry for that service in the Service Configuration Panel (httpd is the service for Apache,<indexterm><primary>Apache</primary></indexterm> while mysqld is the service for MySQL), then click on &ldquo;activate<indexterm><primary>activate</primary></indexterm>&rdquo; or &ldquo;restart<indexterm><primary>restart</primary></indexterm>&rdquo; respectively (<xref linkend="fig-red-hat-service-configuration">).</para><para>Note that in order for our changes in <acronym>PHP</acronym> to take effect, we will have to restart Apache.<indexterm><primary>Apache</primary></indexterm></para><para>Now you can connect to your server by pointing your browser to http://localhost or to http://127.<indexterm><primary>127</primary></indexterm>0.0.1. </para><tip>
<title>Apache and the hosts file</title>
<para>
If the Apache service does not start, it may be because it cannot resolve "localhost" correctly. This name for the local computer is given the IP address 127.0.0.1 in the hosts file (usually under /etc). You can try to change
</para>
<screen>
<![CDATA[
127.0.0.1 localhost.localdomain localhost
]]>
</screen>
<para>
in /etc/hosts to:
</para>
<screen>
<![CDATA[
127.0.0.1 dhcppc0 localhost.localdomain localhost
]]>
</screen>
</tip>
<para>The folder that is expected to hold the HTML files is again /var/www/html. Note that, again, in order for the normal user to be able to modify the HTML files, you will have to change the permissions of that folder to 777<indexterm><primary>777</primary></indexterm> (see <xref linkend="permissions">). </para><para>It is also comfortable to create a link to that folder on the client's desktop, so that he does not have to click his way through the path each time.</para></sect2>
</sect1>
<sect1 id="config-php-file"><title>The config.php file</title><para>The last thing that remains to do before starting with the management of your site, is to configure the file config.<indexterm><primary>config</primary></indexterm>php This is important because it sets up a connection between the <acronym>PHP</acronym> files of <application>PHP-Nuke</application> and the MySQL<indexterm><primary>MySQL</primary></indexterm> database that manages it.</para><important>
<title>Important: Use a decent text editor!</title>
<para>
Do NOT use Notepad or Wordpad to edit the config.php file! These "text" editors don't deserve this name - they introduce extra invisible characters in the file, causing spurious errors with the <acronym>PHP</acronym> interpreter. Everything will look O.K., but you will spend many hours trying to find out why your <acronym>PHP</acronym> tells you there is an error there.
</para>
<para>
Recommended text editors are <ulink url="http://www.ultraedit.com">UltraEdit</ulink> (excellent, but not freeware), <ulink url="http://download.com.com/3000-2352-10140098.html?tag=lst-0-2">Crimson Editor</ulink> , <ulink url="http://download.com.com/3000-2048-10143719.html">WinSyntax</ulink> (both good for <acronym>PHP</acronym> and Freeware, Crimson Editor has some feature more than WinSyntax) and <ulink url="http://www.chami.com/html-kit">HTMLkit</ulink> (free for personal use).
</para>
<para>
Various text editors and their functionalities for <acronym>PHP</acronym> are discussed in this <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=122">decent text editor</ulink> thread.
</para>
</important>
<para>You need to enter a database username and a password in the config.<indexterm><primary>config</primary></indexterm>php file. This user must have administration rights on the <application>PHP-Nuke</application> MySQL database<indexterm><primary>base</primary></indexterm> (whose name you also entered in the config.<indexterm><primary>config</primary></indexterm>php file). You configure this user to have administration rights on the <application>PHP-Nuke</application> database<indexterm><primary>base</primary></indexterm> by either phpMyAdmin,<indexterm><primary>Admin</primary></indexterm> or from the command line:</para><screen><![CDATA[grant all privileges on db.* to dbuser@localhost identified by 'dbpasswd';
]]></screen><note>
<title>Please note</title>
<para>
This is the database user account, on whose behalf everything is done from the database point of view. That is, no matter which user is doing something in PHP-Nuke, when he presses [Enter], the command will be forwarded to the database client, who will connect to the database server with that username and password you entered in the config.php. If that username and password were wrong, or that user did not have "all privileges" on the <application>PHP-Nuke</application> database (the database whose name you entered in the config.php), then the client will not be able to connect and you will get an error (one of these exactly-speaking but nothing-communicating "...was not a valid resource" errors ).
</para>
</note>
<para>Let's have a closer look at the configuration process. Compared to the 5.6 version, the config.<indexterm><primary>config</primary></indexterm>php file has undergone a radical diet, leaving it with only a few lines. The rest has been moved to the nuke_config table (<xref linkend="database-tables">). This has created problems with the Splatt Forum (<xref linkend="administration-functions">), which also used a table with that name. When you open the file &ldquo;config.php<indexterm><primary>config.php</primary></indexterm>&rdquo; you will see the following near the top:</para><screen>
$dbhost = "localhost"; <co id="dbhost">
$dbuname = "root"; <co id="dbuname">
$dbpass = ""; <co id="dbpass">
$dbname = "nuke"; <co id="dbname">
$prefix = "nuke"; <co id="prefix">
$user_prefix = "nuke"; <co id="userprefix">
$dbtype = "MySQL"; <co id="mysql">
$sitekey = "SdFk*fa28367-dm56w69.3a2fDS+e9"; <co id="sitekey">
</screen>
<calloutlist>
<callout arearefs="dbhost">
<para>
In place of "localhost" you will have to put the host/server that the database is installed on. If this is your own computer, the "localhost" is O.K., otherwise you will have to ask your ISP.
</para>
</callout>
<callout arearefs="dbuname">
<para>
In place of "root" you must put the username of the database user that <application>PHP-Nuke</application> will have to use in order to connect to the database and execute the necessary database operations. This user must have been grented all privileges to the <application>PHP-Nuke</application> database as discussed above.
</para>
</callout>
<callout arearefs="dbpass">
<para>
You will have to insert the password of the database user here.
</para>
</callout>
<callout arearefs="dbname">
<para>
In place of "nuke" you will have to insert the name of your database here.
</para>
</callout>
<callout arearefs="prefix">
<para>
I recommend this to be left to its default value, "nuke", is the prefix that goes in front of the name of every database table.
</para>
</callout>
<callout arearefs="userprefix">
<para>
This is the prefix that goes in front of the name of every database user table. The idea here is that you can have one prefix, i.e. one <application>PHP-Nuke</application> database, but many user prefixes, i.e. different user tables for different sites. The user tables will have a different user_prefix in their names, but the rest of the tables will still use prefix, thus sharing the same nuke database among different user bases from different sites.
</para>
</callout>
<callout arearefs="mysql">
<para>
Leave this to "MySQL", if you have a MySQL database (which will be true in most situations). This is case sensitive, so "mysql" or "Mysql" will not do, it has to be exactly "MySQL".
</para>
</callout>
<callout arearefs="sitekey">
<para>
You should change this key to be a unique key that identifies your site. Ideally, no two sites should have the same key.The site key is used to create the random number for the security image (<xref linkend="fig-security-code">) in the Your Account module and the administration section and is an important but often overlooked security feature of <application>PHP-Nuke</application>. See also <xref linkend="security-measures"> for software that can help you create a truly random site key.
</para>
</callout>
</calloutlist>
<para>Let's do an example:</para><itemizedlist><listitem><para>Host DB: 212.110.12.297 </para></listitem><listitem><para>User DB: Pippo </para></listitem><listitem><para>Password DB: Topolino </para></listitem><listitem><para>Database Name: Orazio </para></listitem><listitem><para>Operating System Used: <productname>Linux</productname> (what else!!! :-) )</para></listitem></itemizedlist><para>The file config.<indexterm><primary>config</primary></indexterm>php should then look like:</para><screen><![CDATA[$dbhost = "212.110.12.297";
]]><![CDATA[$dbuname = "Pippo";
]]><![CDATA[$dbpass = "Topolino";
]]><![CDATA[$dbname = "Orazio";
]]><![CDATA[$system = 0;
]]><![CDATA[$prefix = "nuke";
]]><![CDATA[$sitekey = "SdFk*jkjbkuuz-dm98769.4b67DS+e4";
]]></screen><caution>
<title>Attention!</title>
<para>
This is case sensitive! Remember to use The Capital Letters!!! On <productname>Linux</productname> systems, if you write a user name or a password without taking care of letter case, the system will not allow you to log in.
</para>
</caution>
<para>You must distinguish between the database user (and password), which you enter in the config.php file, and the administrator &quot;God&quot;<indexterm><primary>God</primary></indexterm> account. The database user is only known to the database.<indexterm><primary>base</primary></indexterm> The administrator &quot;God&quot;<indexterm><primary>God</primary></indexterm> account (there are also other administrator levels), on the other side, is created by <application>PHP-Nuke</application> automatically for you. This account, as well as the users accounts, exist only in the <application>PHP-Nuke</application> database,<indexterm><primary>base</primary></indexterm> not in the MySQL server's configuration. </para><para>How is this <application>PHP-Nuke</application> administrator created? If you go to the &quot;Home&quot; link of <application>PHP-Nuke</application>., you will then see a message telling you the following - just do what it tells you:</para><blockquote><para>Welcome to PHP-Nuke!</para><para>Congratulations! You have now a web portal installed!. You can edit or change this message from the Administration page. </para><para>For security reasons the best idea is to create the Super User right NOW by clicking HERE </para></blockquote><para>Click on that link and it will create the <application>PHP-Nuke</application> administrator account for you.</para><note>
<title>A superuser is NOT a registered User</title>
<para>
A superuser is an administrator with all admin powers. One should call it superadmin, because everyone gets confused at first. It is fine (and normal) to have a superuser admin and a registered user that have the same name. Be careful with side effects when you are logged in as both, see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=14784">Login Block on Left doesn't go away</ulink>.
</para>
</note>
<para>We are done, the only thing that remains to do is to enter the administration<indexterm><primary>administration</primary></indexterm> section (www.yoursite.com/admin.<indexterm><primary>admin</primary></indexterm>php). The very first time you will log in using &ldquo;God<indexterm><primary>God</primary></indexterm>&rdquo; as username and &ldquo;Password&rdquo; as password.<indexterm><primary>password</primary></indexterm> I recommend you to change these as soon as possible. Immediately after that, you should take some security measures, see <xref linkend="security-measures">.</para><para>The config.<indexterm><primary>config</primary></indexterm>php file also defines two arrays, the $AllowableHTML and $CensorList array. As its name says, $AllowableHTML is an associative array containing entries for all HTML tags that are to be allowed on your site:</para><screen><![CDATA[$AllowableHTML = array("b"=>1,
]]><![CDATA[ "i"=>1,
]]><![CDATA[ "a"=>2,
]]><![CDATA[ "em"=>1,
]]><![CDATA[ "br"=>1,
]]><![CDATA[ "strong"=>1,
]]><![CDATA[ "blockquote"=>1,
]]><![CDATA[ "tt"=>1,
]]><![CDATA[ "li"=>1,
]]><![CDATA[ "ol"=>1,
]]><![CDATA[ "H1"=>1,
]]><![CDATA[ "H2"=>1,
]]><![CDATA[ "H3"=>1,
]]><![CDATA[ "H4"=>1,
]]><![CDATA[ "center"=>1,
]]><![CDATA[ "img"=>2,
]]><![CDATA[ "alt"=>1,
]]><![CDATA[ "table"=>2,
]]><![CDATA[ "tr"=>2,
]]><![CDATA[ "td"=>2,
]]><![CDATA[ "p"=>2,
]]><![CDATA[ "div"=>2,
]]><![CDATA[ "font"=>2,
]]><![CDATA[ "p"=>1,
]]><![CDATA[ "p"=>1,
]]><![CDATA[ "ul"=>1);
]]></screen><para>The meaning of &quot;1&quot; and &quot;2&quot; is whether the tag accepts attributes or not. For example, if you want the &lt;p&gt; tag to NOT accept attributes (i.e. you accept &lt;p&gt; but you don't accept &lt;p align=&quot;center&quot;&gt;) the you put &quot;1&quot;, otherwise (i.e., if attributes like &quot;align&quot; etc. are accepted) you put &quot;2&quot;. That this is indeed so, can be seen from the check_html() function of mainfile.php (see also <xref linkend="allow-special-HTML-tags">):</para><screen><![CDATA[ if ($a = $AllowableHTML[$tag])
]]><![CDATA[ if ($reg[1][0] == "/") $tag = "</$tag>";
]]><![CDATA[ elseif (($a == 1) || ($reg[2] == "")) $tag = "<$tag>";
]]><![CDATA[ else {
]]><![CDATA[ # Place here the double quote fix function.
]]><![CDATA[ $attrb_list=delQuotes($reg[2]);
]]><![CDATA[ // A VER
]]><![CDATA[ $attrb_list = ereg_replace("&","&amp;",$attrb_list);
]]><![CDATA[ $tag = "<$tag" . $attrb_list . ">";
]]><![CDATA[ } # Attribs in tag allowed
]]><![CDATA[ else $tag = "";
]]></screen><para>The code checks if the associated value to the given tag ($tag) in the $AllowableHTML array is &ldquo;1&rdquo; or empty. If this is the case,<indexterm><primary>case</primary></indexterm> the value of $tag is only &ldquo;&lt;$tag&gt;&rdquo;. Otherwise a set of replacements takes place on the attribute list:</para><itemizedlist><listitem><para>The delQuotes() function deletes duplicate space and adds escaped quotes<indexterm><primary>quotes</primary></indexterm> around each attribute value.</para></listitem><listitem><para>The ereg_replace() function replaces the ampersand (&amp;) with its HTML entity<indexterm><primary>entity</primary></indexterm> &ldquo;&amp;amp;&rdquo;.</para></listitem></itemizedlist><para>If the tag is not in the $AllowableHTML array, the line in the code above shows that it is replaced by the empty string, i.e. it is not echoed at all. Thus, if there is an HTML tag that you are missing, you should enter it in the $AllowableHTML array and take care to enter correctly a &ldquo;1&rdquo; or a &ldquo;2&rdquo; according to your needs. See for example <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=94">Smilies in news</ulink>.</para><para>The $CensorList array contains a list of words that you don't want to see in texts of articles on your site. </para><sect2 id="more-than-one-php-nuke-sites"><title>More than one <application>PHP-Nuke</application> sites</title><para>The variables in the config.<indexterm><primary>config</primary></indexterm>php file allow for quite some flexibility when it comes to installing more than one <application>PHP-Nuke</application> sites that have to be related in one or the other way:</para><sect3 id="common-database"><title>Different <application>PHP-Nuke</application> sites from the same database</title><para>If you have two (or more) <application>PHP-Nuke</application> sites, located in different Web URLs (or different local directories), that you want to operate from the same database,<indexterm><primary>base</primary></indexterm> you have some handwork to do, but it is not difficult. From the point of view of the database server,<indexterm><primary>server</primary></indexterm> what differentiates one <application>PHP-Nuke</application> site from another, is the name of the table(s) used. In PHP-Nuke, all tables come with a prefix:<indexterm><primary>prefix</primary></indexterm> the users table uses the $user_prefix prefix from the config.<indexterm><primary>config</primary></indexterm>php file(<xref linkend="config-php-file">), while all other tables use $prefix.<indexterm><primary>prefix</primary></indexterm> </para><para>Thus, you don't need a second database to operate a second <application>PHP-Nuke</application> site. A different database helps keep the installations separate by providing a kind of &ldquo;container&rdquo; to put each installation's tables in, but apart from this, there is nothing special to it. To use only one database for two <application>PHP-Nuke</application> installations,<indexterm><primary>ations</primary></indexterm> proceed as follows:</para><itemizedlist><listitem><para>Use separate $prefix and $user_prefix values in each site's config.php,<indexterm><primary>config.php</primary></indexterm> e.g. </para><screen><![CDATA[$prefix = "nuke1";
]]><![CDATA[$user_prefix = "nuke1";
]]></screen><para>in config.<indexterm><primary>config</primary></indexterm>php for site 1 and </para><screen><![CDATA[$prefix = "nuke2";
]]><![CDATA[$user_prefix = "nuke2";
]]></screen><para>in config.<indexterm><primary>config</primary></indexterm>php for site 2. All other values should stay identical in the config.<indexterm><primary>config</primary></indexterm>php files of both sites.</para></listitem><listitem><para>Edit the nuke.sql file (located under the sql directory of the <application>PHP-Nuke</application> package) for each site. Change every occurence of &ldquo;nuke_&rdquo; to &ldquo;nuke1_&rdquo; for site 1 and to &ldquo;nuke2_&rdquo; for site 2, then proceed with the installation as described in <xref linkend="database-creation">. If you use nukesql.php (<xref linkend="install-PHP-Nuke-nukesql">) for the installation,<indexterm><primary>installation</primary></indexterm> see the tip at the end of this section.</para></listitem></itemizedlist></sect3>
<sect3 id="common-user-base"><title>Different <application>PHP-Nuke</application> sites with the same user base</title><para>There are situations that you might want to share users among your <application>PHP-Nuke</application> sites. For example, if you have a site about cars and another one about car insurance,<indexterm><primary>insurance</primary></indexterm> your users will probably be interested in both. But requiring them to enter two different logins and passwords is not going to make them happy - that's where $user_prefix comes into play.</para><para>The idea behind a separate prefix for the users table in <application>PHP-Nuke</application> is to enable you to keep all other tables separate, but use the same users table across different <application>PHP-Nuke</application> installations.<indexterm><primary>ations</primary></indexterm> By using a different $prefix for each site, but the same $user_prefix for both, your users will require only one login and password - and will be recognized by the second site, while logged into the first one and vice versa.</para><para>To use the same user base in two separate <application>PHP-Nuke</application> sites, proceed as follows:</para><itemizedlist><listitem><para>Use the same database as descibed in <xref linkend="common-database">.</para></listitem><listitem><para>Use separate $prefix values, but the same $user_prefix for both config.php<indexterm><primary>config.php</primary></indexterm> files, e.g. </para><screen><![CDATA[$prefix = "nuke1";
]]><![CDATA[$user_prefix = "nuke-common";
]]></screen><para>in config.<indexterm><primary>config</primary></indexterm>php for site 1 and </para><screen><![CDATA[$prefix = "nuke2";
]]><![CDATA[$user_prefix = "nuke-common";
]]></screen><para>in config.<indexterm><primary>config</primary></indexterm>php for site 2. All other values should stay identical in the config.<indexterm><primary>config</primary></indexterm>php files of both sites.</para></listitem><listitem><para>Edit the nuke.sql file (located under the sql directory of the <application>PHP-Nuke</application> package) for each site. Change every occurence of &ldquo;nuke_&rdquo; to &ldquo;nuke1_&rdquo; for site 1 and to &ldquo;nuke2_&rdquo; for site 2, <emphasis>except the ones for the nuke_users table</emphasis>, which you should change to &ldquo;nuke-common<indexterm><primary>nuke-common</primary></indexterm>&rdquo;. The full name of the users table should thus be &ldquo;nuke-common_users<indexterm><primary>nuke-common_users</primary></indexterm>&rdquo; in both nuke.sql files. Then proceed with the installation as described in <xref linkend="database-creation">. </para></listitem></itemizedlist><tip>
<title>Using nukesql.php</title>
<para>
If you use nukesql.php (<xref linkend="install-PHP-Nuke-nukesql">) for the installation, you should change the prefixes as above and point your browser to each instance of nukesql.php (one for each installation, located in the respective <application>PHP-Nuke</application> root directory). It will then create the tables with the right prefixes for you.
</para>
</tip>
</sect3>
</sect2>
</sect1>
<sect1 id="resources"><title>Resources</title><para>Claudio says: if you are looking for <application>PHP-Nuke</application> hosting,<indexterm><primary>hosting</primary></indexterm> <ulink url="http://www.spaghettibrain.com">Spaghettibrain.com</ulink> has custom offers for you... give us a visit! <ulink url="http://www.spaghettibrain.com">Spaghettibrain.com</ulink> is the italian support site for PHP-Nuke, there you will find modules,<indexterm><primary>modules</primary></indexterm> security patches, support forums and a lot more. Come for a tour soon.</para><para>Other specialized <application>PHP-Nuke</application> hosters:<indexterm><primary>hosters</primary></indexterm></para><itemizedlist><listitem><para><ulink url="http://www.nukezone.com">Nukezone</ulink></para></listitem><listitem><para><ulink url="http://ravenphpscripts.ravenwebhosting.com/index.php">Raven Web Hosting</ulink></para></listitem></itemizedlist></sect1>
<sect1 id="common-installation-problems"><title>Common installation problems</title><para>Some of the most common installation problems of <application>PHP-Nuke</application> are discussed in the following subsections. In identifying the most common sources of problems and frustration,<indexterm><primary>frustration</primary></indexterm> we hope to eliminate a good portion of the Help! posts in the various forums of the community.<indexterm><primary>community</primary></indexterm> Feel free to post your own favourite to Chris' <ulink url="http://www.karakas-online.de/forum/phpnuke.html">PHP-Nuke Forum</ulink>for inclusion in the next version of this HOWTO.<indexterm><primary>HOWTO</primary></indexterm></para><sect2 id="test-scripts"><title>Test scripts</title><para>Before you start the ambitious undertaking of debugging your <application>PHP-Nuke</application> installation, you should download and run some tools that may shorten the search path and save you some headaches:<indexterm><primary>headaches</primary></indexterm></para><itemizedlist><listitem><para>test.<indexterm><primary>test</primary></indexterm>php</para></listitem><listitem><para>ConnectTest.php and</para></listitem><listitem><para>analyze.<indexterm><primary>analyze</primary></indexterm>php</para></listitem></itemizedlist><sect3 id="test-php"><title>test.php</title><para>test.<indexterm><primary>test</primary></indexterm>php is a &ldquo;quick'n dirty&rdquo; script to help you find out if you could connect to the database and how your <acronym>PHP</acronym> configuration looks like. Put the following lines in a file, name it test.<indexterm><primary>test</primary></indexterm>php, upload it in the same directory where you have your config.<indexterm><primary>config</primary></indexterm>php and tell your browser to open it (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=36">Warning: Invalid argument supplied for foreach()</ulink>):</para><screen><![CDATA[<?php
]]><![CDATA[include("config.php");
]]><![CDATA[mysql_connect("$dbhost", "$dbuname", "$dbpass");
]]><![CDATA[mysql_select_db("$dbname");
]]><![CDATA[echo mysql_error();
]]><![CDATA[phpinfo();
]]><![CDATA[?>
]]></screen><para>If everything is right, you will only see the <acronym>PHP</acronym> info.<indexterm><primary>info</primary></indexterm> Otherwise, you will see a descriptive message of the error first (in the first line) and also the <acronym>PHP</acronym> info.<indexterm><primary>info</primary></indexterm> You can use the output to determine various parameters of your <acronym>PHP</acronym> configuration, like version numbers, libraries,<indexterm><primary>libraries</primary></indexterm> paths and variables. Whenever you ask yourself if you have feature X enabled, remember to run this small script and search its output for a string that describes the feature. You will most probably find the answer there. Conversely, if you don't find the answer in the output of test.<indexterm><primary>test</primary></indexterm>php (i.e. the output of the phpinfo() function), you will probably not find it easily.</para></sect3>
<sect3 id="ConnectTest-php"><title>ConnectTest.php</title><para>The <ulink url="http://humpa.com/news/ConnectTest.txt">ConnectTest.php</ulink> script from <ulink url="http://www.humpa.com">Humpa</ulink> is a more elaborate test script that you can help with database connection<indexterm><primary>connection</primary></indexterm> problems. Download and save it with a .php ending (it comes with a .txt ending to prevent<indexterm><primary>event</primary></indexterm> the web server from interpreting the <acronym>PHP</acronym> code in it). You should put the ConnectTest.php file in the <application>PHP-Nuke</application> root directory, i.e. in the same directory where also config.<indexterm><primary>config</primary></indexterm>php is located. Then you just tell your browser to open it.</para><screen><![CDATA[<?php
]]><![CDATA[if($phpinfo=="phpinfo") {
]]><![CDATA[ phpinfo();
]]><![CDATA[ die();
]]><![CDATA[}
]]><![CDATA[require_once("config.php");
]]><![CDATA[$dbcheck = mysql_connect("$dbhost", "$dbuname", "$dbpass");
]]><![CDATA[if (!$dbcheck) {
]]><![CDATA[ echo mysql_error();
]]><![CDATA[ echo "<br><b>The Connection Test Script was unable to connect
]]><![CDATA[to the MySQL server!<br>One or more of these variables are wrong in
]]><![CDATA[your config.php:</b> <font color=purple><b>\$dbhost=\"<i>$dbhost</i>\",
]]><![CDATA[\$dbuname=\"<i>$dbuname</i>\", and/or \$dbpass=\"*<i>hidden</i>*\"
]]><![CDATA[</b></font><br>";
]]><![CDATA[ echo "<br>Now, please don't say that you <u>are</u> using the
]]><![CDATA[correct values - say it to your mysql server, because that is who(what?)
]]><![CDATA[is stopping you. : )<br>";
]]><![CDATA[ echo "Email your web host and ask them what to use for a mysql
]]><![CDATA[username and password.<br>";
]]><![CDATA[ echo "PHP Manual, function:
]]><![CDATA[<a href=\"http://www.php.net/manual/en/function.mysql-connect.php\"
]]><![CDATA[target=\"_blank\">mysql_connect</a><br>";
]]><![CDATA[ echo "If you are the server, perhaps you just need to create
]]><![CDATA[a mysql user instead of using your root user.<br>";
]]><![CDATA[ die("<br><a href=\"$_SERVER[PHP_SELF]?phpinfo=phpinfo\">
]]><![CDATA[phpinfo</a>");
]]><![CDATA[}else{
]]><![CDATA[ echo "<a href=\"$_SERVER[PHP_SELF]?phpinfo=phpinfo\">
]]><![CDATA[phpinfo</a><br><br>";
]]><![CDATA[ echo "<font color=red><b>If everything looks good, but you
]]><![CDATA[still have problems, get the ";
]]><![CDATA[ echo "<a href=\"http://nukecops.com/downloads-cat-7.htm\">
]]><![CDATA[analyzer from NukeCops</a></b></font><br><br>";
]]><![CDATA[ echo "<b>Connection Test Script connected to your MySQL server
]]><![CDATA[successfully!<br>";
]]><![CDATA[ echo "<br>\$dbuname = \"$dbuname\";<br>\$dbtype = \"$dbtype\";
]]><![CDATA[<br>\$prefix = \"$prefix\";<br>\$user_prefix = \"$user_prefix\";<br>";
]]><![CDATA[ if (mysql_select_db($dbname)) {
]]><![CDATA[ echo "<br>Connection to your database \"
]]><![CDATA[<font color=purple>$dbname</font>\" was also successful.<br>";
]]><![CDATA[ $result = mysql_list_tables($dbname);
]]><![CDATA[ if (!$result) {
]]><![CDATA[ print "DB Error, could not list tables\n";
]]><![CDATA[ print 'MySQL Error: ' . mysql_error();
]]><![CDATA[ die();
]]><![CDATA[ }
]]><![CDATA[ $i=0;
]]><![CDATA[ $stufftoprint = "";
]]><![CDATA[ while ($row = mysql_fetch_row($result)) {
]]><![CDATA[ $tablename = $row[0];
]]><![CDATA[ if($tablename == "".$prefix."_authors") {
]]><![CDATA[ $result4 = mysql_query("select aid from $tablename");
]]><![CDATA[ while(list($admin_name) = mysql_fetch_row($result4)) {
]]><![CDATA[ $admin_names .= "$admin_name, &nbsp;";
]]><![CDATA[ }
]]><![CDATA[ }
]]><![CDATA[ $result3 = mysql_query("select * from $tablename");
]]><![CDATA[ $numFields = mysql_num_fields($result3);
]]><![CDATA[ $numRows = mysql_num_rows($result3);
]]><![CDATA[ $rows = "rows";
]]><![CDATA[ $fields = "fields";
]]><![CDATA[ if($numFields == 1) {$fields = "field";}
]]><![CDATA[ if($numRows == 1) {$rows = "row";}
]]><![CDATA[ $stufftoprint .= "Table: <font color=purple>$tablename
]]><![CDATA[</font> &nbsp;($numFields $fields / $numRows $rows)\n<br>";
]]><![CDATA[ $i++;
]]><![CDATA[ }
]]><![CDATA[ if($dbtype != "MySQL" AND eregi("mysql",$dbtype)) {
]]><![CDATA[ echo "<br><font color=red><b>But, you need to set </b>
]]><![CDATA[</font><font color=purple><b> \$dbtype = \"MySQL\"; </b></font>";
]]><![CDATA[ echo "<font color=red><b> &nbsp;&nbsp; in your config.php!!!!!!!!</b></font><br>";
]]><![CDATA[ }
]]><![CDATA[ echo "<br>There are <font color=purple>$i tables</font> in your \"
]]><![CDATA[<font color=purple>$dbname</font>\" database<br>";
]]><![CDATA[ echo "(by default, there are 89 fields in phpnuke 6.5 and 76 fields
]]><![CDATA[in phpnuke 6.0)<br>";
]]><![CDATA[ if($i<66) {
]]><![CDATA[ echo "<br><font color=red><b>You don't seem to have all the
]]><![CDATA[tables installed.<br>Get the ";
]]><![CDATA[ echo "<a href=\"http://www.nukeresources.com/modules.php?name=Downloads
]]><![CDATA[&d_op=viewdownload&cid=79\">Web Installer</a> for your version of
]]><![CDATA[phpnuke</b></font><br>";
]]><![CDATA[ }
]]><![CDATA[ echo "<br>These are the admin names (aid) in your nuke_authors
]]><![CDATA[table: &nbsp;<font color=purple>$admin_names</font><br>";
]]><![CDATA[ echo "<br>Now check this list of tables with your nuke.sql file:<br><br>$stufftoprint</b>";
]]><![CDATA[ }else {
]]><![CDATA[ if(mysql_query("CREATE DATABASE $dbname")) {
]]><![CDATA[ echo "<br>Your database \"$dbname\" did not exist,
]]><![CDATA[but this script just created it sucessfully<br>";
]]><![CDATA[ echo "Now, you need to get the appropriate
]]><![CDATA[<a href=\"http://www.nukeresources.com/modules.php?name=Downloads
]]><![CDATA[&d_op=viewdownload&cid=79\">";
]]><![CDATA[ echo "Web Installer from nukeresources.com</a>";
]]><![CDATA[ die();
]]><![CDATA[ }
]]><![CDATA[ echo "<br>However, the \"$dbname\" database does not exist.
]]><![CDATA[If that is not the correct name, then put in the correct ";
]]><![CDATA[ echo "name for<br><font color=purple>
]]><![CDATA[\$dbname =\"$dbname\";</font>&nbsp;&nbsp; (in your config.php)
]]><![CDATA[<br>If you have not created the database yet, then ";
]]><![CDATA[ echo "create it. If you are not the server, then ask your
]]><![CDATA[web host to create it for you.<br>";
]]><![CDATA[ echo "<br>Then, get the appropriate
]]><![CDATA[<a href=\"http://www.nukeresources.com/modules.php?name=Downloads
]]><![CDATA[&d_op=viewdownload&cid=79\">";
]]><![CDATA[ echo "Web Installer from nukeresources.com</a>";
]]><![CDATA[ }
]]><![CDATA[}
]]><![CDATA[?>
]]><![CDATA[
]]></screen></sect3>
<sect3 id="analyze-php"><title>analyze.php</title><para>The <ulink url="http://nukecops.com/downloads-file-13-details-Analyzer.html">analyze.php</ulink> script from Paul Laudanski (a.k.a. <ulink url="http://zhen-xjell.com">Zhen-Xjell</ulink>) is the most elaborate from all the three script presented here. Rename the file to &quot;analyze.<indexterm><primary>analyze</primary></indexterm>php&quot;, transfer it to the same place that your config.<indexterm><primary>config</primary></indexterm>php file is found and call it from your browser. For a preview of what it reports, <ulink url="http://nukecops.com/analyze.php">run analyze.php for the nukecops site</ulink>. The code has been successfully tested for Nuke versions 6.5B6, 6.5B5,<indexterm><primary>6.5B5</primary></indexterm> 6.0, 5.6.</para><para>
<figure id="fig-analyze-mysql-connection">
<title>
analyze.php: MySQL connection transcript.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1028;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1028;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1028;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1028;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>analyze.php: MySQL connection transcript.</phrase>
</textobject>
<caption>
<para>analyze.php: MySQL connection transcript.</para>
</caption>
</mediaobject>
</figure>
</para><para>The script not only tests your MySQL database connection (see <xref linkend="fig-analyze-mysql-connection">), but also displays information on:</para><itemizedlist><listitem><para>config.<indexterm><primary>config</primary></indexterm>php settings</para></listitem><listitem><para>SMTP (mail server) settings<indexterm><primary>settings</primary></indexterm></para></listitem><listitem><para>GD (graphics) library settings<indexterm><primary>settings</primary></indexterm></para></listitem><listitem><para>Databases</para></listitem><listitem><para>Modules<indexterm><primary>Modules</primary></indexterm></para></listitem><listitem><para>Blocks<indexterm><primary>Blocks</primary></indexterm></para></listitem><listitem><para>Notices</para></listitem><listitem><para>Ranks<indexterm><primary>Ranks</primary></indexterm></para></listitem><listitem><para>Administrators and Moderators</para></listitem><listitem><para>php,ini settings<indexterm><primary>settings</primary></indexterm></para></listitem><listitem><para>Security code</para></listitem><listitem><para>Recursive file listing along with resource permissions<indexterm><primary>permissions</primary></indexterm></para></listitem></itemizedlist><para>
<figure id="fig-analyze-warning-mysql">
<title>
analyze.php: MySQL security warning.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1029;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1029;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1029;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1029;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>analyze.php: MySQL security warning.</phrase>
</textobject>
<caption>
<para>analyze.php: MySQL security warning.</para>
</caption>
</mediaobject>
</figure>
</para><para>It also checks for MySQL (see <xref linkend="fig-analyze-warning-mysql">) and <acronym>PHP</acronym> (see <xref linkend="fig-analyze-warning-php">) vulnerabilities and reports them to you if they need to be patched.</para></sect3>
</sect2>
<sect2 id="Warning-mysql-fetch-row-supplied-argument"><title>Warning: mysql_fetch_row(): supplied argument is not a valid MySQL result resource</title><para>You get this</para><screen><![CDATA[Warning: mysql_fetch_row(): supplied argument is not a valid MySQL result
]]><![CDATA[resource in html/includes/sql_layer.php on line 286
]]></screen><para>This is a very general error. Most of the time it just means that you could not connect to the database<indexterm><primary>base</primary></indexterm> (for whatever reason) and thus the result set you tried to fetch was not a &ldquo;valid MySQL result resource&rdquo;. You should try first to get a more descriptive error message. For this purpose, you must edit the &quot;case&quot; lines in the sql_layer.<indexterm><primary>layer</primary></indexterm>php file.</para><para>Example:This is the &quot;case&quot; that starts at line 286 in the nuke 6.5 sql_layer.<indexterm><primary>layer</primary></indexterm>php (for the line 286 error), at line 300 in the nuke 6.0 sql_layer.<indexterm><primary>layer</primary></indexterm>php (for the line 301 error message) - or line 285 in nuke 5.6 (for the line 286 error message):</para><screen><![CDATA[ case "MySQL":
]]><![CDATA[ $row = mysql_fetch_row($res);
]]><![CDATA[ return $row;
]]><![CDATA[ break;;
]]></screen><para>Edit it like this:</para><screen><![CDATA[ case "MySQL":
]]><![CDATA[ if ($row = mysql_fetch_row($res)) {
]]><![CDATA[ return $row;
]]><![CDATA[ } else {
]]><![CDATA[ print (mysql_error());
]]><![CDATA[ }
]]><![CDATA[ break;;
]]></screen><note>
<title>Please note:</title>
<para>
This will NOT fix your problem. But it will give a more descriptive message as to what the error cause is.
</para>
</note>
<para>See <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=37">Warning: mysql fetch row: supplied argument is not a valid MySQL result resource</ulink> and <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=14121">submit news problem</ulink>.</para></sect2>
<sect2 id="call-to-undefined-function"><title>Call to undefined function: message_die() in db.php line 88</title><para>This is the most &ldquo;popular&rdquo; error. It basically means that it couldn't connect to the database.<indexterm><primary>base</primary></indexterm> You may get this error even if you did everything right, depending on the version you are using. The reasons are multiple:</para><itemizedlist><listitem><para>Are you sure you downloaded *all* the files? Maybe some file is missing. Perhaps you wanted to save some bandwidth and omitted some crucial file or directory, or subdirectory.<indexterm><primary>subdirectory</primary></indexterm></para></listitem><listitem><para>You didn't enter &quot;MySQL&quot;<indexterm><primary>MySQL</primary></indexterm> as the dbtype in config.php (see <xref linkend="config-php-file">). It must be exactly with a Capital M, a small y, and capital S, Q and L.</para></listitem><listitem><para>The code tries to select the database,<indexterm><primary>base</primary></indexterm> but the database is not there. Create the database and populate it with tables (see <xref linkend="database-creation">).</para></listitem><listitem><para>You have some error in the config.<indexterm><primary>config</primary></indexterm>php file (see <xref linkend="config-php-file">). Double check that the username and password are correct. Don't forget, the &quot; and ; <emphasis>are</emphasis> important. And DON'T remove the $ in front of the variables! If you used an editor<indexterm><primary>editor</primary></indexterm> like Notepad, Wordpad,<indexterm><primary>Wordpad</primary></indexterm> or some editor that you are not 100% sure that works correctly, delete the config.<indexterm><primary>config</primary></indexterm>php file, get a fresh copy and edit it with a <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=122">decent text editor</ulink> (see <xref linkend="editing-PHP-Nuke-files">).</para></listitem></itemizedlist></sect2>
<sect2 id="failed-opening-lang-php"><title>Error: Failed opening 'language/lang-.php' for inclusion</title><para>You either </para><itemizedlist><listitem><para>didn't install the language files lang-xxx.php (like language/lang-english.php), or </para></listitem><listitem><para>you cannot connect to the database,<indexterm><primary>base</primary></indexterm> so that the value of the default language could not be set and is empty (and that's why you get an error about lang-.php,<indexterm><primary>lang-.php</primary></indexterm> instead of lang-english.php, or lang-french.<indexterm><primary>french</primary></indexterm>php etc.). Try the small test script (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?p=72">Call to undefined function: message die in db.php line 88</ulink>):</para><screen><![CDATA[<?php
]]><![CDATA[include("config.php");
]]><![CDATA[mysql_connect("$dbhost", "$dbuname", "$dbpass");
]]><![CDATA[mysql_select_db("$dbname");
]]><![CDATA[echo mysql_error();
]]><![CDATA[phpinfo();
]]><![CDATA[?>
]]></screen><para>(see also <xref linkend="test-scripts">), or</para></listitem><listitem><para>your include path information is missing some paths (like &quot;.&quot;, the current directory), see <xref linkend="Include-path">.</para></listitem></itemizedlist></sect2>
<sect2 id="failed-opening-sql-layer-php"><title>Fatal error: Failed opening required 'includes/sql_layer.php' </title><para>Your web server could not open includes/sql_layer.<indexterm><primary>layer</primary></indexterm>php. There are many reasons for this (<ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=17">Fatal error: Failed opening required includes/sql layer.php</ulink>): </para><itemizedlist><listitem><para>The file is really not there, something went wrong with the installation<indexterm><primary>installation</primary></indexterm> - reinstall (see <xref linkend="installation">).</para></listitem><listitem><para>The file is there but the web server does not have the right to open it - check permissions (see <xref linkend="permissions">).</para></listitem><listitem><para>There is a .htaccess file somewhere in the directory hierarchy that denies access to you. </para></listitem><listitem><para>There is something wrong with the include path of the <acronym>PHP</acronym> interpreter (see <xref linkend="Include-path">).</para></listitem></itemizedlist><para>You might see more information on the cause of your problem if you have access to the web server access and error logs.</para></sect2>
<sect2 id="sorry-such-file-doesnt-exist"><title>Sorry, such file doesn't exist...</title><para>Whenever you try to access a module (or simply your site), you ge the error (see, for example: <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=143">Humpa Chess Install</ulink> and <ulink url="Fehler: Sorry, such file doesn't exist">http://www.karakas-online.de/forum/viewtopic.php?t=348</ulink>):</para><screen><![CDATA[Sorry, such file doesn't exist...
]]></screen><para>Of course, following a classic attitude to error handling, it doesn't tell you which file does not exist...<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_frown.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_frown.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_frown.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_frown.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> We thus have to search the code to see what is happening:</para>
<para>The error</para><screen><![CDATA[Sorry, such file doesn't exist...
]]></screen><para>comes from mainfile.php.<indexterm><primary>mainfile.php</primary></indexterm> There are exactly three occurences of it in the code. In all three the pattern is the same (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=353">Sorry, such file doesn't exist...</ulink>):</para><orderedlist><listitem><para><indexterm><primary>Enumerate</primary></indexterm>First it is tested if you are a normal user, an administrator,<indexterm><primary>administrator</primary></indexterm> if the module is active etc., depending on the circumstances.</para></listitem><listitem><para><indexterm><primary>Enumerate</primary></indexterm>Then, a test is made on the existence of $modpath. Upon its failure,<indexterm><primary>failure</primary></indexterm> you get the error above:</para></listitem></orderedlist><screen><![CDATA[$modpath .= "modules/$name/$file.php";
]]><![CDATA[if (file_exists($modpath)) {
]]><![CDATA[ include($modpath);
]]><![CDATA[} else {
]]><![CDATA[ die ("Sorry, such file doesn't exist...");
]]><![CDATA[}
]]></screen><para>$modpath, in turn, is the path to the module in question. As you can see in the code snippet yourself, it depends on the value of $name, which is the name of the module,<indexterm><primary>module</primary></indexterm> and $file, which is...well, for this you have to scroll up to the start of mainfile.php.<indexterm><primary>mainfile.php</primary></indexterm> There, we read</para><screen><![CDATA[if (!isset($file)) { $file="index"; }
]]></screen><para>which in plain english says &quot;if the variable $file is NOT set, set it to 'index'&quot;.</para><para>Putting all the puzzle pieces together, we arrive to the conclusion that the file</para><screen><![CDATA[modules/YourModule/index.php
]]></screen><para>is not there.</para><para>There are various things you should check and all have to do with trying to find out why your web server cannot find the index file of the module<indexterm><primary>module</primary></indexterm> you are trying to access:<indexterm><primary>access</primary></indexterm></para><itemizedlist><listitem><para>Is the index.<indexterm><primary>index</primary></indexterm>php file really there in the modules/YourModule folder?</para></listitem><listitem><para>Did you set up the permissions (<xref linkend="permissions">, <xref linkend="permissions2">) correctly? Does your web server have read access to that folder and file?</para></listitem><listitem><para>Is there a (hidden) .htaccess file (<xref linkend="htaccess-file">) somewhere in your document tree that prevents the web browser from accessing that file?</para></listitem><listitem><para>Did you install all files? You have to dive in the docs of that module to see if you are missing anything.</para></listitem><listitem><para>Check if</para><screen><![CDATA[http://www.yoursite.com/modules/YourModule/index.php
]]></screen><para>returns an error. Substitute YourModule with the name of the module that is giving you the headaches.<indexterm><primary>headaches</primary></indexterm></para></listitem><listitem><para>If this is a module you downloaded and installed yourself (as opposed to a preinstalled one, see <xref linkend="preinstalled-modules">): Did you really follow the instructions? Did you download the right file? Did you extract it in the modules folder?</para></listitem><listitem><para>Did you see the module in the list of modules and did you activate it (<xref linkend="administration-functions"> and <xref linkend="fig-modules-admin-2">)?</para></listitem></itemizedlist><para>
<figure id="fig-modules-admin-2">
<title>
Modules administration panel.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1030;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1030;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1030;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1030;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Modules administration panel.</phrase>
</textobject>
<caption>
<para>Modules administration panel.</para>
</caption>
</mediaobject>
</figure>
</para></sect2>
<sect2 id="warning-setlocale"><title>Warning: setlocale(): Passing locale category name as string is deprecated</title><para>All of a sudden, you get tons of warnings like this one:</para><screen><![CDATA[Warning: setlocale(): Passing locale category name as string is deprecated.
]]><![CDATA[Use the LC_* -constants instead.
]]><![CDATA[in /home/chris/public_html/nuke/mainfile.php on line 565
]]></screen><para>The problem comes suddenly after your ISP has upgraded to a newer version of <acronym>PHP</acronym> (without telling you, of course! <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_frown.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_frown.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_frown.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_frown.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
<para>To fix this, remove the quotes that are around &quot;LC_TIME&quot;<indexterm><primary>LC_TIME</primary></indexterm> in the line/file mentioned in the error message displayed (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=21">Warning: setlocale(): Passing locale category name as string is deprecated</ulink> and <ulink url="">News article: Warning: setlocale(): Passing locale category name as string is deprecated.</ulink>).</para><caution>
<title>Attention: repetitious error!</title>
<para>
You may get this error again and again. You will have to do the above change in *all* occurences of the LC_something constants! I once counted 17 of them, scattered all around the <application>PHP-Nuke</application> files...
</para>
</caution>
</sect2>
<sect2 id="security-code"><title>Security code is not showing up</title><para>
<figure id="fig-security-code">
<title>
Security code in the User Login screen.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1031;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1031;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1031;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1031;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Security code in the User Login screen.</phrase>
</textobject>
<caption>
<para>Security code in the User Login screen.</para>
</caption>
</mediaobject>
</figure>
</para><para>You just installed <application>PHP-Nuke</application> for the first time, created a super user, and you can't log in because the security code graphic (see <xref linkend="fig-security-code">) is coming up as a dead image.<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_frown.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_frown.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_frown.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_frown.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
<para>This is a frequent error, but it seems that the reasons (and cures) may be multiple (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=22">Security code graphic not showing up</ulink>, <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=14758">security image stopped working</ulink>):</para><itemizedlist><listitem><para>You changed something in the language files and put comments - remove the comments.<indexterm><primary>comments</primary></indexterm></para></listitem><listitem><para>You (or your ISP) don't have the GD library loaded. To find out if you have the GD library loaded, run a test script like test.<indexterm><primary>test</primary></indexterm>php (see <xref linkend="test-php">), ConnectTest.php (see <xref linkend="ConnectTest-php">) or analyze.<indexterm><primary>analyze</primary></indexterm>php (see <xref linkend="analyze-php">). The first two display the output of the <acronym>PHP</acronym> phpinfo() function directly ( <xref linkend="fig-phpinfo-gd">), analyze.<indexterm><primary>analyze</primary></indexterm>php will display an only slightly different information box on GD (<xref linkend="fig-analyze-gd">). If you are on <productname>Windows</productname> 2000, read <ulink url="http://forums.devshed.com/archive/5/2002/08/3/41595">how to install GD on a Win2K box</ulink>.</para></listitem><listitem><para>The gfx function in admin.<indexterm><primary>admin</primary></indexterm>php is not always working fine. You could try to put it in a separate file and change the call from admin.php<indexterm><primary>admin.php</primary></indexterm> to the new file. See Humpa's posting in <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=14550">Admin Security login jpeg not showing</ulink> for an example.</para></listitem><listitem><para>Activate (or reactivate) the Your Account module.<indexterm><primary>module</primary></indexterm> If your Admin's security code works, but the others don't (showing an read X mark for others), then you may want to set the Your Account module as viewable by <emphasis>all</emphasis> visitors (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=299">PhpNuke 6.5 Security Code Problem</ulink>). </para></listitem></itemizedlist><para>
<figure id="fig-phpinfo-gd">
<title>
phpinfo(): GD library information.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1032;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1032;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1032;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1032;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>phpinfo(): GD library information.</phrase>
</textobject>
<caption>
<para>phpinfo(): GD library information.</para>
</caption>
</mediaobject>
</figure>
</para><para>For more thoughts on this problem, read <ulink url="http://www.humpa.com/HelpMeHumpa/index.php?humpa_id=3#h3">Humpa's <application>PHP-Nuke</application> FAQ on the security code</ulink>. </para><para>If you want to use a PNG or GIF image for the security code, consult the solution in <ulink url="http://www.nukefixes.com/postlite44-0.html">Using a png or gif for security code image</ulink>. If you want to display the security code as text, rather than an image, see <ulink url="http://www.nukefixes.com/postlite76-0.html">security code in plain text format</ulink> - but then there is no point to it (the idea is to display an image that makes automatic number recognition difficult to robots), then you can disable it just as well.</para><para>
<figure id="fig-analyze-gd">
<title>
analyze.php: GD library information.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1033;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1033;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1033;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1033;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>analyze.php: GD library information.</phrase>
</textobject>
<caption>
<para>analyze.php: GD library information.</para>
</caption>
</mediaobject>
</figure>
</para><sect3 id="bypass-security-code"><title>How to bypass the security code</title><para>Another approach could be to bypass the security code altogether. This is probably the only option you have (unless you are willing to display it as plain text - see the links at the end of this section for this), if your ISP refuses to load the GD library:<indexterm><primary>library</primary></indexterm> without GD, no security code image - without security code image, you cannot enter anything in the security<indexterm><primary>security</primary></indexterm> code field, and you get an &ldquo;Access denied&rdquo; error. </para><para>Here is how you disable the security code:</para><para>Find the 7 occurences of:</para><screen><![CDATA[extension_loaded("gd")
]]></screen><para>For the Admin login,<indexterm><primary>login</primary></indexterm> there is one in the admin.php, and one in the auth.php. For Users, there will be five in the modules/Your_Account/index.<indexterm><primary>index</primary></indexterm>php (and there might be one in the block-Login.php,<indexterm><primary>block-Login.php</primary></indexterm> and/or one in the block-User_Info.php, if they are modified). Replace all of the occurances with this:</para><screen><![CDATA[$user == "whatever"
]]></screen><para>Follow the above instruction exactly. </para><caution>
<title>Be careful not to introduce syntax errors!</title>
<para>
Changes like the last one (bypassing the security code) require extreme caution on your part. All too big is the risk of introducing new errors, while trying to correct old ones! If you get an error, it does't mean the solution ceased to work for you. Check for syntax errors that you might have introduced with your editing. Most probably, you will find something.
<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject>
See <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=18076">syntax error, security images removed</ulink> for a real world example.
</para>
</caution>
<para>If you have one of the later versions of PHP-Nuke, you can try a trick: edit the config.<indexterm><primary>config</primary></indexterm>php file and if you find a line there, like this one:</para><screen><![CDATA[$gfx_chk = 7;
]]></screen><para>and change it to (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=266">How to disable the security code</ulink>):</para><screen><![CDATA[$gfx_chk = 0;
]]></screen></sect3>
</sect2>
<sect2 id="warning-invalid-argument-supplied"><title>Warning: Invalid argument supplied for foreach() in mainfile.php</title><para>You get errors and warnings like:</para><screen><![CDATA[Warning: Invalid argument supplied for foreach() in ...mainfile.php on line 42
]]><![CDATA[Warning: Invalid argument supplied for foreach() in ...mainfile.php on line 57
]]><![CDATA[Warning: Cannot add header information - headers already sent by
]]><![CDATA[(output started at ...mainfile.php:42) in ...mainfile.php on line 165
]]><![CDATA[
]]></screen><para>You must have at least <acronym>PHP</acronym> v. 4.1.0 to run <application>PHP-Nuke</application> 6.5 and later. See <xref linkend="prerequisites"> and <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=36">Warning: Invalid argument supplied for foreach()</ulink>.</para></sect2>
<sect2 id="Include-path"><title>Include path is wrong</title><para>If the include path happens to be wrong (you can see your include path in the output of test.<indexterm><primary>test</primary></indexterm>php, see <xref linkend="test-scripts">), you could try the following: </para><para>Suppose your nuke files are in /usr/local/httpd/htdocs/nuke/html (just an example ). Suppose that this is the directory that contains</para><para>the includes directory beneath it. Then create a .htaccess file (<xref linkend="htaccess-file">) that contains the line </para><screen><![CDATA[php_value include_path .:/usr/local/httpd/htdocs/nuke/html/includes
]]></screen><para>(no equal signs, just copy it in the .htaccess file). In most cases the include path will be correctly configured. In the few ones that it's not, the most probable cause of errors will be a missing &ldquo;current directory&rdquo; (a missing dot in the include path).</para><para>If you have access to the php.ini file, you can do the same there. Find the line where include_path is defined and add the dot in the list, e.g.:</para><para>include_path = &ldquo;.:/usr/local/httpd/htdocs/nuke/html/includes<indexterm><primary>includes</primary></indexterm>&rdquo;</para><para>See also <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=381">Warning: main(/db/db.php): failed to open stream</ulink> and <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=17">Fatal error: Failed opening required 'includes/sql_layer.php"</ulink>.</para></sect2>
<sect2 id="mail-problems"><title>Users don't receive any confirmation mails</title><para>This is not a <application>PHP-Nuke</application> error. <application>PHP-Nuke</application> uses PHP's mail() function and this, in turn, uses the mail server<indexterm><primary>server</primary></indexterm> that is found on the web server.<indexterm><primary>server</primary></indexterm> If that mail server is configured incorrectly, you will get problems with mail. The best way to solve them is to talk to your ISP and try to find out which configuration is used for your case.<indexterm><primary>case</primary></indexterm> We have seen cases of ISPs that would configure the mail server to deliver mail only to local domains,<indexterm><primary>domains</primary></indexterm> thus making communication between <application>PHP-Nuke</application> and users of other domains impossible (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=137">E-mail problems</ulink>, <ulink url="http://www.nukeforums.com/forums/viewtopic.php?p=56082">my nuke only sends mail to my domain</ulink>).</para><para>Now, what do you do after you have fixed your mail server?<indexterm><primary>server</primary></indexterm> Those e-mails with the activation links have already been sent once, and since they never reached their destinations.<indexterm><primary>ations</primary></indexterm>.. You are losing users because you cannot resend them! </para><para>If you ever needed to resend an activation email, or just wanted to delete one that was awaiting activation,<indexterm><primary>activation</primary></indexterm> then you will appreciate the <ulink url="http://ravenphpscripts.com/download-file-59.html">Resend module</ulink>. It will help you manage the temp_users table.</para><para>If you want users to be registered directly, without confirmation mails, see <xref linkend="register-users-immediately">. If you want to disable registration,<indexterm><primary>registration</primary></indexterm> see <xref linkend="disable-registration">. If you want to approve every user who applied for registration,<indexterm><primary>registration</primary></indexterm> you can use the Approve Membership module (see <xref linkend="PHP-Nuke-Approve-Membership-module"> and <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=83">Authorize accounts</ulink>).</para></sect2>
<sect2 id="login-loop"><title>Login loop</title><para>
<figure id="fig-login-screen">
<title>
User Login screen.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1034;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1034;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1034;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1034;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>User Login screen.</phrase>
</textobject>
<caption>
<para>User Login screen.</para>
</caption>
</mediaobject>
</figure>
</para><para>You login without problems, but whenever you try to access a function or links of the <application>PHP-Nuke</application> site, you are returned to the login screen and are asked to enter your user name and password again - a very annoying procedure!</para><para>The first thing you should check, is if you have cookies enabled in your browser. <application>PHP-Nuke</application> uses cookies to store authentication information on your computer (in the cookies file, see also <xref linkend="cookies">), in order to be able to recognize you on your next page request (remember, HTTP is a stateless protocol,<indexterm><primary>protocol</primary></indexterm> meaning that, whenever the web server serves you a page you requested, it forgets about it, so the next page request is seen as being completely unrelated to the previous one). Thus, you must have cookies enabled to use <application>PHP-Nuke</application>.</para><para>If enabling cookies does not make the problem disappear, it might be a permissions problem (see <xref linkend="permissions">), in which case you should contact the administrator of the site.</para><tip>
<title>
3rd party cookies
</title>
<para>
If you are experimenting with frames, you will find out that the cookie will be set fine, as long as the frame and the parent page are on the same site. If the frame is a different site than the parent, then you will have to allow 3rd party cookies (a lower security setting), see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=13433">Why do users have to put security to "low" to be able to log</ulink>.
</para>
</tip>
</sect2>
<sect2 id="SQL-syntax-error"><title>You have an error in your SQL syntax near '-------------</title><para>When you try to create the database tables with the nuke.sql file (see <xref linkend="database-creation">), you get an error:</para><screen><![CDATA[--
]]><![CDATA[---------------------------------------------------------
]]><![CDATA[--
]]><![CDATA[--
]]><![CDATA[CREATE TABLE confirm (
]]><![CDATA[ confirm_id char(32) NOT NULL default ",
]]><![CDATA[ session_id char(32) NOT NULL default ",
]]><![CDATA[ code char(6) NOT NULL default ",
]]><![CDATA[ PRIMARY KEY (session_id,confirm_id)
]]><![CDATA[) TYPE=MyISAM
]]><![CDATA[MySQL said:
]]><![CDATA[You have an error in your SQL syntax near '---------------------------------------------------------
]]><![CDATA[--
]]><![CDATA[--
]]><![CDATA[CREATE TABLE co' at line 2
]]></screen><para>This is because your nuke.sql file came with nice, useless long lines containing dashes,<indexterm><primary>dashes</primary></indexterm> like these ones:</para><screen><![CDATA[---------------------------------------------------------
]]></screen><para>Just use a <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=122">decent text editor</ulink> (see <xref linkend="editing-PHP-Nuke-files">) and delete that long line, or put a # in front of it. If that doesn't help, put a # in front of every line that starts with a dash, making it a comment. SQL accepts &ldquo;--&rdquo; as the string that starts a comment, but it seems that MySQL does not like the rest of the dashes (after the first two ones) as a comment.</para></sect2>
<sect2 id="error-update-private-forum-permissions"><title>Error: Couldn't update private forum permissions</title><para>
<figure id="fig-forum-3">
<title>
Administration panel: Forums.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1035;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1035;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1035;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1035;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Forums.</phrase>
</textobject>
<caption>
<para>Administration panel: Forums.</para>
</caption>
</mediaobject>
</figure>
</para><para>You get the following error everytime you try to make a particular user (or a site administrator) a moderator in <application>PHP-Nuke</application> 6.5-7.0:<indexterm><primary>7.0</primary></indexterm></para><screen><![CDATA[Couldn't update private forum permissions
]]><![CDATA[DEBUG MODE
]]><![CDATA[SQL Error : 1064 You have an error in your SQL syntax near ' 1)' at line 2
]]><![CDATA[INSERT INTO nuke_bbauth_access (forum_id, group_id, auth_mod) VALUES (3, , 1)
]]><![CDATA[Line : 385
]]><![CDATA[FIle: xxxx/modules/Forums/admin/admin_ug_auth.php
]]></screen><para>This is a bug modules/Forums/admin/admin_ug_auth.php - the INSERT statement is missing a string value in the VALUES clause.<indexterm><primary>clause</primary></indexterm> Try this <ulink url="http://www.nukeresources.com/files/admin_ug_auth.zip">admin_ug_auth.php</ulink> instead. See <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=16633">Couldn't update private forum permissions</ulink> and <ulink url="http://www.nukecops.com/postp77425.html">Site Admin & Moderator</ulink> for more details.</para></sect2>
<sect2 id="invalid-session-in-forums"><title>Invalid session in forums</title><para>
<figure id="fig-forum-4">
<title>
Administration panel: Forums.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1036;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1036;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1036;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1036;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Forums.</phrase>
</textobject>
<caption>
<para>Administration panel: Forums.</para>
</caption>
</mediaobject>
</figure>
</para><para>You installed the <application>PHP-Nuke</application> Forum (which is the phpBB forum starting v.6.5<indexterm><primary>6.5</primary></indexterm> of PHP-Nuke, see <xref linkend="phpBB-Forum-administration">), but now, when you try to access it you get the error: </para><screen><![CDATA[Invalid session.
]]></screen><para>Solution: In the forum configuration,<indexterm><primary>configuration</primary></indexterm> go to the Cookies section and change the name of the cookie file from &quot;phpbb2mysql &quot; to something more original or unique, like &quot;phpbb2mysql2&quot;<indexterm><primary>phpbb2mysql2</primary></indexterm> . You also need to have the right cookie domain,<indexterm><primary>domain</primary></indexterm> i.e. if you have installed the forum under http://yoursite.com/nuke/html, the cookie domain should be http://yoursite.com/nuke/html too. </para><para>&ldquo;What is this session id anyway?&rdquo;, you may ask. This is quite a technical matter and is covered in detail in <xref linkend="session-management">.</para></sect2>
<sect2 id="cannot-create-administrator-account"><title>You cannot create the administrator account</title><para>
<figure id="fig-edit-admins-2">
<title>
Administration panel: Edit Admins.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1037;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1037;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1037;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1037;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Edit Admins.</phrase>
</textobject>
<caption>
<para>Administration panel: Edit Admins.</para>
</caption>
</mediaobject>
</figure>
</para><para>Everything looks fine with your newly created <application>PHP-Nuke</application> site, then you are told by the system that there is no administrator yet and you should create one:</para><screen><![CDATA[There are no Administrators Accounts yet, proceeed to create the Super User:
]]></screen><para>You do what you are told and create that Super User,<indexterm><primary>User</primary></indexterm> but the next time you get the same message. It seems that you cannot create the administrator account!</para><para>The message that asks you to create the Super User is the _NOADMINYET message whose translation you can find in the various language files (see <xref linkend="General-PHP-Nuke-texts">) in the admin/language folder. For example, in admin/language/lang-english.php,<indexterm><primary>lang-english.php</primary></indexterm> we read:</para><para>define(&quot;_NOADMINYET&quot;<indexterm><primary>_NOADMINYET</primary></indexterm>,&quot;There are no Administrators Accounts yet, proceeed to create the Super User:<indexterm><primary>User</primary></indexterm>&quot;);</para><para>The _NOADMINYET message is output in admin.php:<indexterm><primary>admin.php</primary></indexterm></para><screen><![CDATA[$the_first = $db->sql_numrows($db->sql_query("SELECT * FROM ".$prefix."_authors"));
]]><![CDATA[if ($the_first == 0) {
]]><![CDATA[ if (!$name) {
]]><![CDATA[ include("header.php");
]]><![CDATA[ title("$sitename: "._ADMINISTRATION."");
]]><![CDATA[ OpenTable();
]]><![CDATA[ echo "<center><b>"._NOADMINYET."</b></center><br><br>"
]]></screen><para>From the code we see that it is echoed only if $the_first is 0, meaning no entries in the $prefix_authors table. Thus, for some reason, the nuke_authors table (assuming your $prefix is &quot;nuke&quot; in config.<indexterm><primary>config</primary></indexterm>php), is not filled. You can do the following (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=289">I cant make my Admin acount work</ulink>):</para><para>You should check the entries in nuke_authors.<indexterm><primary>nuke_authors</primary></indexterm> You can do this either from the MySQL prompt with</para><screen><![CDATA[select aid, name, email, pwd from nuke_authors;
]]></screen><para>or with the &quot;browse&quot; function of phpMyAdmin (<xref linkend="phpmyadmin2">).</para><para>If your Super Admin is there, then it is weird...<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_frown.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_frown.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_frown.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_frown.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
<para>If the Super Admin is not there, then you can't write to the database.<indexterm><primary>base</primary></indexterm> To check this possibility, find the function create_first() in admin.php.<indexterm><primary>admin.php</primary></indexterm> There, you will see two lines with a call to sql_query.<indexterm><primary>query</primary></indexterm> They are both identical:</para><screen><![CDATA[$db->sql_query($sql);
]]></screen><para>Insert the line:</para><screen><![CDATA[echo mysql_error();
]]></screen><para>after each one. This will echo a more descriptive error message (see <xref linkend="descriptive-error-message">) and may lead you to the solution. But, as experience shows (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=289">I cant make my Admin acount work</ulink>), you most probably have set the wrong values in your config.php (<xref linkend="config-php-file">).<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject>This is a known issue and a solution is presented in <xref linkend="RSS-block-error">.</para>
<screen><![CDATA[
]]></screen></sect2>
<sect2 id="administrator-password-lost"><title>You lost the administrator password, or deleted the admin account</title><para>
<figure id="fig-edit-admins-3">
<title>
Administration panel: Edit Admins.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1038;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1038;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1038;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1038;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Edit Admins.</phrase>
</textobject>
<caption>
<para>Administration panel: Edit Admins.</para>
</caption>
</mediaobject>
</figure>
</para><para>You did a Very Big Mistake - you erased your <application>PHP-Nuke</application> Super Admin! Now you cannot do anything on your website! Your powers are those of a normal member... <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_frown.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_frown.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_frown.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_frown.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject>How do you get your Admin back? </para>
<para>You can try one of the following two solutions (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=11">I deleted my Super Admin. How do I get him back?</ulink>):</para><orderedlist><listitem><para><indexterm><primary>Enumerate</primary></indexterm>You can use phpMyAdmin (or a similar DB administration package, see <xref linkend="phpmyadmin">) and look in (the technical term on the link is &ldquo;browse&rdquo;) the nuke_authors table. You can take two approaches:</para><orderedlist><listitem><para><indexterm><primary>Enumerate</primary></indexterm>See if your admin is still there, and you can set a new password (you'll have to choose &ldquo;MD5<indexterm><primary>MD5</primary></indexterm>&rdquo; from the dropdown menu on the pass field, see <xref linkend="fig-phpmyadmin-field-functions-2">). If your admin is not there, then just add a new row to the table and put in the missing info.<indexterm><primary>info</primary></indexterm> </para></listitem><listitem><para><indexterm><primary>Enumerate</primary></indexterm>Or you can just delete the line with the administrator name and point your browser to the admin.<indexterm><primary>admin</primary></indexterm>php file - you will then be prompted to enter a new admin name and password.<indexterm><primary>password</primary></indexterm> You may enter whatever new values you like there, but you should not create a user with the same name, even if prompted to.</para></listitem></orderedlist></listitem><listitem><para><indexterm><primary>Enumerate</primary></indexterm>Using phpMyAdmin (or directly in MySQL), go to the nuke_authors table and make your password dc647eb65e6711e155375218212b3964 - that will make it Password, then just login and change it. Here we make use of the fact that the MD5 hash of the word &ldquo;Password&rdquo; is dc647eb65e6711e155375218212b3964.</para></listitem></orderedlist><para>
<figure id="fig-phpmyadmin-field-functions-2">
<title>
phpMyAdmin: field functions.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1039;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1039;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1039;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1039;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>phpMyAdmin: field functions.</phrase>
</textobject>
<caption>
<para>phpMyAdmin: field functions.</para>
</caption>
</mediaobject>
</figure>
</para><tip>
<title>
How to compute the MD5 hash of an arbitrary password using only <acronym>PHP</acronym> and your browser
</title>
<para>
If you are curious about the MD5 hash of a certain password, but do not have easy access to a function that computes it, you can make use of the fact that the <acronym>PHP</acronym> interpreter of your web server can compute is for you. Substitute XXXX for the password whose MD5 hash you want to compute in the following script:
</para>
<screen>
<![CDATA[<?php]]>
<![CDATA[$pass="XXXX";]]>
<![CDATA[$new_password = md5($pass);]]>
<![CDATA[print("MD5 hash of $pass = $new_password");]]>
<![CDATA[?>]]>
</screen>
<para>
and upload it somewhere on your web server. Then point your browser to it and you should see the answer. You can use it to change the password field of the nuke_authors table directly in MySQL.
</para>
</tip>
<para>See <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=11383">Admin Password - i've lost it</ulink>, <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=18212">Password help</ulink> for discussions.</para></sect2>
<sect2 id="garbage-on-page"><title>You get garbage in some parts of the page</title><para>If some parts of your page looks like containing garbage,<indexterm><primary>garbage</primary></indexterm> it may be due to a compressed output from the server.<indexterm><primary>server</primary></indexterm> You could try to disable compression by just commenting the line (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=289">I cant make my Admin acount work</ulink>):</para><screen><![CDATA[ob_start('ob_gzhandler');
]]></screen><para>or setting $do_gzip_compress to FALSE:</para><screen><![CDATA[$do_gzip_compress = FALSE;
]]></screen><para>in mainfile.php.<indexterm><primary>mainfile.php</primary></indexterm> The part that controls compression in mainfile.php is:</para><screen><![CDATA[$phpver = phpversion();
]]><![CDATA[if ($phpver >= '4.0.4pl1' && strstr($HTTP_USER_AGENT,'compatible')) {
]]><![CDATA[ if (extension_loaded('zlib')) {
]]><![CDATA[ ob_end_clean();
]]><![CDATA[ ob_start('ob_gzhandler');
]]><![CDATA[ }
]]><![CDATA[} else if ($phpver > '4.0') {
]]><![CDATA[ if (strstr($HTTP_SERVER_VARS['HTTP_ACCEPT_ENCODING'], 'gzip')) {
]]><![CDATA[ if (extension_loaded('zlib')) {
]]><![CDATA[ $do_gzip_compress = TRUE;
]]><![CDATA[ ob_start();
]]><![CDATA[ ob_implicit_flush(0);
]]><![CDATA[ //header('Content-Encoding: gzip');
]]><![CDATA[ }
]]><![CDATA[ }
]]><![CDATA[}
]]></screen><para>You might even have to comment it completely (see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=16439">PhpNuke wont show in IE or Opera</ulink>).</para></sect2>
<sect2 id="compressed-output-in-forums"><title>Compressed output in forums</title><para>
<figure id="fig-forum-gzip-compression">
<title>
Gzip compression in the Admin Panel of the Forums module.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1040;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1040;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1040;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1040;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Gzip compression in the Admin Panel of the Forums module.</phrase>
</textobject>
<caption>
<para>Gzip compression in the Admin Panel of the Forums module.</para>
</caption>
</mediaobject>
</figure>
</para><para>You seem to be getting a compressed output in the forums. You are either seeing garbage, or you can see it in IE, but not in Mozilla.<indexterm><primary>Mozilla</primary></indexterm> When you press &ldquo;Refresh<indexterm><primary>Refresh</primary></indexterm>&rdquo;, Mozilla reacts like you want to download something that is &ldquo;encrypted<indexterm><primary>encrypted</primary></indexterm>&rdquo; or compressed.</para><para>All this is a sign that you may be compressing the page twice. If, for example, your Apache has been already configured to send compressed output (with <ulink url="http://www.schroepl.net/projekte/mod_gzip/index.htm">mod_gzip</ulink>, or some other technique for <ulink url="http://perl.apache.org/docs/tutorials/client/compression/compression.html">Web Content Compression</ulink>), then you should disable gzip compression in the forums administration<indexterm><primary>administration</primary></indexterm> panel (from &ldquo;General Admin,<indexterm><primary>Admin</primary></indexterm> Configuration&rdquo;, as in <xref linkend="fig-forum-gzip-compression">).</para><para>See also <ulink url="http://www.nukeforums.com/forums/viewtopic.php?p=58655">Cannot see forum in Mozilla and see in IE</ulink>.</para></sect2>
<sect2 id="cannot-add-header-information-in-forums"><title>Warning: Cannot add header information...in forums</title><para>You get errors of the form:</para><screen><![CDATA[Warning: Cannot modify header information headers already sent
]]></screen><para>when vieweing the forums. There are two solutions (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=291">Warning: Cannot add header information...in forums</ulink>):</para><orderedlist><listitem><para><indexterm><primary>Enumerate</primary></indexterm>Near the start of mainfile.php find:</para><screen><![CDATA[42 = phpversion();
]]><![CDATA[if (42 >= '4.0.4pl1' && strstr(Mozilla/4.0 (compatible; MSIE 6.0; <productname>Windows</productname> NT 5.1),'compatible')) {
]]><![CDATA[ if (extension_loaded('zlib')) {
]]><![CDATA[ ob_end_clean();
]]><![CDATA[ ob_start('ob_gzhandler');
]]><![CDATA[ }
]]><![CDATA[} else if (42 > '4.0') {
]]></screen><para>and change it to:</para><screen><![CDATA[42 = phpversion();
]]><![CDATA[if (42 >= '4.0.4pl1')
]]><![CDATA[{
]]><![CDATA[ ob_start('ob_gzhandler');
]]><![CDATA[}else if (42 > '4.0') {
]]></screen></listitem><listitem><para>Add the following line to a .htaccess file (see <xref linkend="htaccess-file">) placed in your root <application>PHP-Nuke</application> directory:</para><screen><![CDATA[PHP_FLAG output_buffering on
]]></screen><para>or if you have access to php.ini,<indexterm><primary>php.ini</primary></indexterm> set:</para><screen><![CDATA[output_buffering=on;
]]></screen></listitem></orderedlist><para>See also <ulink url="http://www.nukefixes.com/postt36.html">Warning: Cannot modify header information on Forums</ulink> and <ulink url="http://www.nukeforums.com/forums/viewtopic.php?p=56538">Cannot modify header information</ulink>. To learn more about <acronym>PHP</acronym> output buffering,<indexterm><primary>buffering</primary></indexterm> see <ulink url="http://www.devshed.com/Server_Side/PHP/OutputBuffering/">Output Buffering with PHP</ulink> and <ulink url="http://jinxidoru.com/tutorials/buffering.html">PHP Output Buffering tutorial</ulink>.</para><screen><![CDATA[
]]></screen></sect2>
<sect2 id="empty-page-in-windows"><title>In Windows, you get an empty page</title><para>You installed Apache, <acronym>PHP</acronym> and MySQL in <productname>Windows</productname>. It seems to work, but when you try to run PHP-Nuke's index page, the browser starts searching the page without showing anytihg. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_frown.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_frown.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_frown.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_frown.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject>How do you get your Admin back? </para>
<para>This is too vague an error to trace down to anything specific with certainty, but there are indications (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=257">Problems with header function</ulink>) that it is related to the header() function of <acronym>PHP</acronym> and <ulink url="http://bugs.php.net/bug.php?id=16842">PHP's Bug #16842: header() function doesn`t work</ulink>. The bug seems to have been fixed in newer versions of PHP,<indexterm><primary>PHP</primary></indexterm> but it might still appear, if you had a previous version that you did not uninstall cleanly (the old problem with DLLs not being correctly managed under Windows,<indexterm><primary>Windows</primary></indexterm> with old versions still lying around even after an uninstall). If you suspect this might be the case with you, uninstall <acronym>PHP</acronym> cleanly and reinstall.<indexterm><primary>reinstall</primary></indexterm></para></sect2>
<sect2 id="lots-of-Notice-lines"><title>You get a lot of Notice lines in the output of PHP-Nuke</title><para>If you get lots of Notice lines in your <application>PHP-Nuke</application> output like this:</para><screen><![CDATA[Notice: No prefix specified in import_request_variables()
]]><![CDATA[- possible security hazard in
]]><![CDATA[c:\program files\apache group\apache\htdocs\html\mainfile.php on line 23
]]><![CDATA[
]]><![CDATA[Notice: Constant _ youhave already defined in
]]><![CDATA[c:\program files\apache group\apache\htdocs\html\language\lang-english.php on line 158
]]><![CDATA[
]]><![CDATA[Notice: Use of undefined constant admin - assumed 'admin'
]]><![CDATA[in c:\program files\apache group\apache\htdocs\html\admin.php on line 16
]]><![CDATA[
]]><![CDATA[Notice: Use of undefined constant admin - assumed 'admin'
]]><![CDATA[in c:\program files\apache group\apache\htdocs\html\mainfile.php on line 88
]]><![CDATA[
]]><![CDATA[Notice: Constant _yes already defined in
]]><![CDATA[c:\program files\apache group\apache\htdocs\html\admin\language\lang-english.php on line 24
]]><![CDATA[
]]><![CDATA[Notice: Constant _no already defined in
]]><![CDATA[c:\program files\apache group\apache\htdocs\html\admin\language\lang-english.php on line 25
]]></screen><para>then the error level for the reporting is too high (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=221">A lot of Notice lines in the output of PHP-Nuke</ulink>). Set display_errors so that <acronym>PHP</acronym> will display all errors, except notices, in your php.ini.<indexterm><primary>php.ini</primary></indexterm> Edit php.ini with a <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=122">decent text editor</ulink> (see also <xref linkend="editing-PHP-Nuke-files">) as follows - the important line is the last one, which is the only uncommented one:</para><screen><![CDATA[;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
]]><![CDATA[; Error handling and logging ;
]]><![CDATA[;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
]]><![CDATA[; error_reporting is a bit-field. Or each number up to get desired error
]]><![CDATA[; reporting level
]]><![CDATA[; E_ALL - All errors and warnings
]]><![CDATA[; E_ERROR - fatal run-time errors
]]><![CDATA[; E_WARNING - run-time warnings (non-fatal errors)
]]><![CDATA[; E_PARSE - compile-time parse errors
]]><![CDATA[; E_NOTICE - run-time notices (these are warnings which often result
]]><![CDATA[; from a bug in your code, but it's possible that it was
]]><![CDATA[; intentional (e.g., using an uninitialized variable and
]]><![CDATA[; relying on the fact it's automatically initialized to an
]]><![CDATA[; empty string)
]]><![CDATA[; E_CORE_ERROR - fatal errors that occur during PHP's initial startup
]]><![CDATA[; E_CORE_WARNING - warnings (non-fatal errors) that occur during PHP's
]]><![CDATA[; initial startup
]]><![CDATA[; E_COMPILE_ERROR - fatal compile-time errors
]]><![CDATA[; E_COMPILE_WARNING - compile-time warnings (non-fatal errors)
]]><![CDATA[; E_USER_ERROR - user-generated error message
]]><![CDATA[; E_USER_WARNING - user-generated warning message
]]><![CDATA[; E_USER_NOTICE - user-generated notice message
]]><![CDATA[;
]]><![CDATA[; Examples:
]]><![CDATA[;
]]><![CDATA[; - Show all errors, except for notices
]]><![CDATA[;
]]><![CDATA[;error_reporting = E_ALL & ~E_NOTICE
]]><![CDATA[;
]]><![CDATA[; - Show only errors
]]><![CDATA[;
]]><![CDATA[;error_reporting = E_COMPILE_ERROR|E_ERROR|E_CORE_ERROR
]]><![CDATA[;
]]><![CDATA[; - Show all errors except for notices
]]><![CDATA[;
]]><![CDATA[error_reporting = E_ALL & ~E_NOTICE
]]><![CDATA[
]]></screen></sect2>
<sect2 id="descriptive-error-message"><title>How to get a more descriptive error message</title><para>If you get an error, but you have no idea what is happening, you could try to narrow it down in the code, if you feel comfortable with <acronym>PHP</acronym>.<indexterm><primary>PHP</primary></indexterm> Then, after you found the offending line, you should insert the line</para><screen><![CDATA[print (mysql_error());
]]></screen><para>immediately after it. This will give a more descriptive message of the error and hopefully lead you to a solution. We already used this trick in <xref linkend="Warning-mysql-fetch-row-supplied-argument">. See also <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=37">Warning: mysql fetch row: supplied argument is not a valid MySQL result resource</ulink> and <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=14121">submit news problem</ulink>.</para></sect2>
</sect1>
<sect1 id="common-miscellaneous-errors"><title>Common miscellaneous errors</title><para>Some miscellaneous errors are discussed here.</para><sect2 id="RSS-block-error"><title>RSS block Error: There is a current problem with the headlines from this site</title><para>If you encounter the error</para><screen><![CDATA[There is a current problem with the headlines from this site
]]></screen><para>after some innocent changes in an RSS block, you are not alone. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject>This is a known issue and a solution is presented in <xref linkend="RSS-block-error">.</para>
</sect2>
<sect2 id="MySQL-errno-145"><title>MySQL errno: 145: Can't open file nuke_XXXX.MYI</title><para>If suddenly you get an error like:</para><screen><![CDATA[Could not insert new word matches
]]><![CDATA[DEBUG MODE
]]><![CDATA[SQL Error : 1016 Can't open file: 'nuke_bbsearch_wordmatch.MYI'. (errno: 145)
]]><![CDATA[INSERT INTO nuke_bbsearch_wordmatch (post_id, word_id, title_match)
]]><![CDATA[SELECT 4467, word_id, 0 FROM nuke_bbsearch_wordlist WHERE word_text IN ('testing')
]]><![CDATA[Line : 282
]]><![CDATA[File : /xxxx/xxxx/public_html/nuke/includes/functions_search.php
]]></screen><para>then you will know that your MySQL database has been corrupted. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_frown.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_frown.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_frown.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_frown.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject>In the above example, the nuke_bbsearch_wordmatch table is damaged (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=332">MySQL errno: 145 Can't open file nuke bbsearch wordmatch.MYI</ulink>).</para>
<para>Solution: Enter the MySQL prompt from the shell:<indexterm><primary>shell</primary></indexterm></para><screen><![CDATA[mysql -u dbuname -h dbhost -p dbname;
]]></screen><para>where dbuname,<indexterm><primary>dbuname</primary></indexterm> dbhost and dbname are exactly the same as in your config.php (<xref linkend="config-php-file">) - you will also be prompted for your password,<indexterm><primary>password</primary></indexterm> which must also be the same as in config.php - and try the REPAIR TABLE command:<indexterm><primary>command</primary></indexterm></para><screen><![CDATA[repair table nuke_bbsearch_wordmatch;
]]></screen><para>You can also try from the shell command-line the myisamchl utility:<indexterm><primary>utility</primary></indexterm></para><screen><![CDATA[myisamchk -r nuke_bbsearch_wordmatch
]]></screen><para>See <xref linkend="repair-corrupt-table"> on how to repair corrupt tables.<indexterm><primary>tables</primary></indexterm></para></sect2>
<sect2 id="modules-disappear"><title>Modules do not show up and/or disappear</title><para>
<figure id="fig-modules-4">
<title>
Administration panel: Modules.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1041;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1041;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1041;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1041;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Modules.</phrase>
</textobject>
<caption>
<para>Administration panel: Modules.</para>
</caption>
</mediaobject>
</figure>
</para><para>In <application>PHP-Nuke</application> version 7 alpha, when adding a module to the modules folder it won't show in admin/modules.<indexterm><primary>modules</primary></indexterm> When renaming a module,<indexterm><primary>module</primary></indexterm> with FTP or similar, the module also disappears (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=306">Modules do not show and/or disappear</ulink>).</para><para>The problem is that in admin/modules/modules.<indexterm><primary>modules</primary></indexterm>php, of that version, on the line that inserts the modules in the folder modules,<indexterm><primary>modules</primary></indexterm> the number of fields is incorrect. In admin/modules/modules.<indexterm><primary>modules</primary></indexterm>php, the lines with:</para><screen><![CDATA[ if ($mid == "") {
]]><![CDATA[ sql_query("insert into ".$prefix."_modules
]]><![CDATA[values (NULL, '$modlist[$i]', '$modlist[$i]', '0', '0', '1')", $dbi);
]]><![CDATA[ }
]]></screen><para>should have been:</para><screen><![CDATA[ if ($mid == "") {
]]><![CDATA[ sql_query("insert into ".$prefix."_modules
]]><![CDATA[values (NULL, '$modlist[$i]', '$modlist[$i]', '0', '0', '1', '0')", $dbi);
]]><![CDATA[ }
]]></screen><para>Notice the <emphasis>extra</emphasis> </para><screen><![CDATA[,'0'
]]></screen><para>before the </para><screen><![CDATA[)",$dbi);
]]></screen><para>This error seems to affect v. 7 alpha and some of the 7.0 FINAL downloads.<indexterm><primary>ads</primary></indexterm> </para><para>You should also be aware that there are some third party modules which alter<indexterm><primary>alter</primary></indexterm> the nuke_modules table. All you have to do to determine if this might be a problem for you, is to view your nuke_modules table through phpMyAdmin (<xref linkend="phpmyadmin">) or a similar tool, count the number of fields and then compare this number with the code in admin/modules.<indexterm><primary>modules</primary></indexterm>php:</para><screen><![CDATA[if ($mid == "") {
]]><![CDATA[ sql_query("insert into ".$prefix."_modules
]]><![CDATA[values (NULL, '$modlist[$i]', '$modlist[$i]', '0', '0', '1', '0')", $dbi);
]]><![CDATA[}
]]></screen><para>The above gives us 7 fields.</para></sect2>
<sect2 id="forums-cant-create-category-without-name"><title>Forums Error: Can't create a category without a name</title><para>You want to create a category in the Forum (see <xref linkend="phpBB-Forum-administration">), but you get the error:</para><screen><![CDATA[General Error
]]><![CDATA[Can't create a category without a name
]]></screen><para>Your strategy in coping with error messages, in case your error is not obvious or not well explained by the message, is to search the whole code tree for the error text (just as you would search for a link text in <xref linkend="find-all-registration-links">). In this case,<indexterm><primary>case</primary></indexterm> it turns out that there is only one occurence, in modules/Forums/admin/admin_forums.php:</para><screen><![CDATA[case 'addcat':
]]><![CDATA[ // Create a category in the DB
]]><![CDATA[ if( trim($HTTP_POST_VARS['categoryname']) == '')
]]><![CDATA[ {
]]><![CDATA[ message_die(GENERAL_ERROR, "Can't create a category without a name");
]]><![CDATA[ }
]]></screen><para>As you can easily see, the error is issued if the category name contains only &quot;white space&quot;<footnote><para>&ldquo;White space<indexterm><primary>space</primary></indexterm>&rdquo;, in the setting of the <acronym>PHP</acronym> trim(), function can contain only the following characters:</para><itemizedlist><listitem><para>&quot; &quot; (ASCII 32 (0x20)), an ordinary space.<indexterm><primary>space</primary></indexterm></para></listitem><listitem><para>&quot;\t&quot; (ASCII 9 (0x09)), a tab.</para></listitem><listitem><para>&quot;\n&quot; (ASCII 10 (0x0A)), a new line (line feed).</para></listitem><listitem><para>&quot;\r&quot; (ASCII 13 (0x0D)), a carriage return.</para></listitem><listitem><para>&quot;\0&quot; (ASCII 0 (0x00)), the NUL-byte.<indexterm><primary>NUL-byte</primary></indexterm></para></listitem><listitem><para>&quot;\x0B&quot; (ASCII 11 (0x0B)), a vertical tab. </para></listitem></itemizedlist></footnote> (which is what the <ulink url="http://www.php.net/manual/en/function.trim.php">PHP trim function</ulink> strips from the beginning and end of a string), in simple words:<indexterm><primary>words</primary></indexterm> if you did not enter any name for the category.<indexterm><primary>category</primary></indexterm> Logical, isn't it?</para><para>But what happens if you swear that you <emphasis>did</emphasis> enter a name there? Isn't this error going to drive you nuts then? </para><para>In such situations,<indexterm><primary>ations</primary></indexterm> you should keep your calmness and try to think further than the obvious: what could be happenning behind the scenes in PHP-Nuke? Here are some possibilities (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=357">Can't create a category without a name</ulink>):</para><orderedlist><listitem><para>You entered an empty name - O.K., you already checked that, but let's include it, just for the sake of completeness. This means that $HTTP_POST_VARS['categoryname'], the value of the POST<indexterm><primary>POST</primary></indexterm> variable that holds the category name, is empty, or contains at most some white space.<indexterm><primary>space</primary></indexterm></para></listitem><listitem><para>Your browser does not send POST variables back to the server,<indexterm><primary>server</primary></indexterm> e.g. it does not support forms. Also quite unlikely.</para></listitem><listitem><para>$HTTP_POST_VARS['categoryname'] was not empty when it arrived at PHP-Nuke, but <application>PHP-Nuke</application> changed it. In fact, <application>PHP-Nuke</application> subjects the POST and GET variables to some sanity checks (see <xref linkend="security-audit"> for details), to see if they contain malicious code. If your category name contained any &ldquo;forbidden&rdquo; characters, it may be that some check routine in <application>PHP-Nuke</application> deleted it. Try a name that will not raise suspicions of SQL injection (<xref linkend="SQL-injection-with-php-nuke">) and similar attacks.</para></listitem><listitem><para>You are logged in as the administrator <emphasis>and</emphasis> as a user. In this case,<indexterm><primary>case</primary></indexterm> you browser has stored two cookies (<xref linkend="cookies">) on your computer and it is not clear under what <acronym>ID</acronym> your action has been evaluated by <application>PHP-Nuke</application>. Try to avoid such situations.<indexterm><primary>ations</primary></indexterm> If you must me logged in as both a user and an administrator at all costs,<indexterm><primary>costs</primary></indexterm> you might try to use two different browsers for each <acronym>ID</acronym> (not two instances of the same browser, but two different products). They will store the cookies in different locations and will (hopefully) not mess them up.</para></listitem></orderedlist><para>Of course, YMMV. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
</sect2>
<sect2 id="missing-blocks"><title>Left and right blocks are missing</title><para>
<figure id="fig-missing-blocks">
<title>
Missing blocks.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1042;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1042;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1042;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1042;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Missing blocks.</phrase>
</textobject>
<caption>
<para>Missing blocks.</para>
</caption>
</mediaobject>
</figure>
</para><para>If your <application>PHP-Nuke</application> site looks like the one in <xref linkend="fig-missing-blocks">, i.e. lacking totally the left and right columns with all the blocks in them, then maybe your nuke_blocks table is corrupt (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=416">Missing blocks and modules</ulink>, as well as <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=17061">My blocks are gone</ulink> and <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=18204">Blocks have disappeared</ulink>). See <xref linkend="repair-corrupt-table"> on how to repair a corrupt table.</para></sect2>
</sect1>
</chapter>
<chapter id="upgrade-php-nuke"><title>How to upgrade PHP-Nuke</title><para>The upgrade of your <application>PHP-Nuke</application> system to a new version is done in the following steps:<indexterm><primary>steps</primary></indexterm></para><itemizedlist><listitem><para>Make a database backup.<indexterm><primary>backup</primary></indexterm> (See <xref linkend="fig-backup-db"> and <xref linkend="administration-functions">, for PHP-Nuke's own backup function,<indexterm><primary>function</primary></indexterm> <xref linkend="phpmyadmin"> for phpMyAdmin's functionality, which also includes a very good web interface<indexterm><primary>interface</primary></indexterm> to database backups and <xref linkend="backup-mysql-using-browser">, for home-made scripts that automate the backup work for you.)</para></listitem><listitem><para>Verify that your current <application>PHP-Nuke</application> version has not been modified (excluding the theme,<indexterm><primary>theme</primary></indexterm> that does not needs an update). In case it has been modified through the addition of modules that required a change in the original <application>PHP-Nuke</application> files, or the database,<indexterm><primary>base</primary></indexterm> proceed manually as outlined in <xref linkend="install-modules-with-database-files-change">.</para></listitem><listitem><para>Test the upgrade locally first and not directly on the production site.</para></listitem><listitem><para>If all looks well, transfer the files and the database to the production site.</para></listitem></itemizedlist><para>The update to a new version itself, is an operation that consists of two parts, the update of the database and the overwriting of the old files with the new ones. The update of the database is done automatically through appropriate scripts that can be found in the upgrades folder of the <application>PHP-Nuke</application> package. You have to upload the right upgrade script to your <application>PHP-Nuke</application> root directory on the server (where also config.<indexterm><primary>config</primary></indexterm>php is located), then point your browser to it - this will update the database.<indexterm><primary>base</primary></indexterm> See also <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=240">How to upgrade PHP-Nuke</ulink> and <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=258">PHP-Nuke upgrade</ulink>.</para><para>If you are upgrading from a version that is more than one version apart from the version you are aiming at, then you have to apply all patches sequencially, from the old one, through any intermediate versions, up to the newest one. Thus, for the passage of 6.6 to 6.8, you must apply both upgrade66-67.php<indexterm><primary>upgrade66-67.php</primary></indexterm> and upgrade67-68.php.<indexterm><primary>upgrade67-68.php</primary></indexterm></para><para>If you are upgrading from 5.6 to 6.0, you must also overwrite the config.php<indexterm><primary>config.php</primary></indexterm> file with the new one, then edit it again with the right values (see <xref linkend="config-php-file">).</para><para>The following sections cover some examples in detail.</para><sect1 id="upgrade-php-nuke-60-65"><title>From 6.0 to 6.5</title><para>See <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=15248">phpNuke Upgrade from 6.0 to 6.5</ulink>.</para><sect2 id="upgrade-instructions-60-without-bbtonuke"><title>Upgrade instructions for <application>PHP-Nuke</application> 6.0 without Tom's bbtonuke port</title><orderedlist><listitem><para>Make a backup of the database tables and all files.</para></listitem><listitem><para>Using your current config.php as a guide configure the new config.php's settings, <application>PHP-Nuke</application> 6.5's config.php has a new variable: $sitekey, it is recommended that you change at least some of the letters/numbers in it to make it unique.</para></listitem><listitem><para>Upload all files and folders included in Nuke's html folder so that they replace your current files.</para></listitem><listitem><para>Upload upgrade60-65.php to Nuke's main directory (where config.php is) and point your browser to it. Delete it once done.</para></listitem><listitem><para>If you were using Splatt forum with Nuke 6.0 and wish to transfer its data into the new bbtonuke forum, use NSN_Move</para></listitem></orderedlist></sect2>
<sect2 id="upgrade-instructions-60-with-bbtonuke"><title>Upgrade instructions for <application>PHP-Nuke</application> 6.0 with Tom's 2.0.6 bbtonuke port</title><orderedlist><listitem><para>Make a backup of the database tables and all files.</para></listitem><listitem><para>Using your current config.php as a guide configure the new config.php's settings, <application>PHP-Nuke</application> 6.5's config.php has a new variable: $sitekey, it is recommended that you change at least some of the letters/numbers in it to make it unique.</para></listitem><listitem><para>Upload all files and folders included in Nuke's html folder so that they replace your current files.</para></listitem><listitem><para>Upload nukebbsql.php to Nuke's main directory (where config.php is) and point your browser to it. Delete it once done.</para></listitem></orderedlist></sect2>
</sect1>
<sect1 id="upgrade-phpbb-php-nuke"><title>From phpBB to PHP-Nuke</title><para>If you have an existing phpBB Forum and would like to integrate it into one of the newer <application>PHP-Nuke</application> versions that come with phpBB Forums, you should use the <ulink url="http://www.ruleit.co.uk/nuke/forums/viewtopic.php?t=524">phpBB to <application>PHP-Nuke</application> Script</ulink> from the <application>PHP-Nuke</application> UK Forums. To install it, put the code into a file, edit the variables at the top and save it as transfer.php,<indexterm><primary>transfer.php</primary></indexterm> for example. Upload the file to the same directory as your <application>PHP-Nuke</application> config.<indexterm><primary>config</primary></indexterm>php and point your browser to it. See also <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=419">How to integrate new <application>PHP-Nuke</application> with existing phpBB Forum</ulink>.</para><caution>
<title>Always backup!</title>
<para>
Backup both your <application>PHP-Nuke</application> database and your phpBB database before running this script.
</para>
</caution>
</sect1>
<sect1 id="PHP-Nuke-upgrade-scripts"><title>PHP-Nuke upgrade scripts</title><para>What's in an upgrade script? Let's take a few representative examples of code and explain what they do, so that you get an idea of what is going on in such a script<footnote><para>We will assume all prefixes, like $prefix and $user_prefix to be &ldquo;nuke&rdquo;.</para></footnote>:</para><variablelist><varlistentry><term>UPDATE&nbsp;(Version&nbsp;number):
</term><listitem><para>the <application>PHP-Nuke</application> version is updated in the nuke_config<indexterm><primary>nuke_config</primary></indexterm> table through the UPDATE command:<indexterm><primary>command</primary></indexterm></para><screen><![CDATA[// <application>PHP-Nuke</application> Version Number Update
]]><![CDATA[$db->sql_query("UPDATE ".$prefix."_config SET Version_Num='6.7'");
]]></screen></listitem></varlistentry><varlistentry><term>UPDATE&nbsp;(Forums):
</term><listitem><para>some forum parameters are modified through the UPDATE command.<indexterm><primary>command</primary></indexterm></para><screen><![CDATA[// <application>PHP-Nuke</application> Forums Update
]]><![CDATA[$db->sql_query("UPDATE ".$prefix."_bbconfig SET config_value='.0.4' where
]]><![CDATA[config_name='version'");
]]><![CDATA[$db->sql_query("UPDATE ".$prefix."_bbconfig SET config_value='3600' where
]]><![CDATA[config_name='session_length'");
]]></screen></listitem></varlistentry><varlistentry><term>INSERT:<indexterm><primary>INSERT</primary></indexterm>
</term><listitem><para>some values are inserted into the nuke_bbconfig table through the INSERT command:<indexterm><primary>command</primary></indexterm></para><screen><![CDATA[$db->sql_query("INSERT INTO ".$prefix."_bbconfig VALUES ('config_id','1')");
]]></screen></listitem></varlistentry><varlistentry><term>DELETE:
</term><listitem><para>a recorde is deleted from the nuke_headlines table through the DELETE<indexterm><primary>DELETE</primary></indexterm> command<indexterm><primary>command</primary></indexterm></para><screen><![CDATA[$db->sql_query("DELETE FROM ".$prefix."_headlines WHERE
]]><![CDATA[sitename='Linux.com'");
]]></screen></listitem></varlistentry><varlistentry><term>DROP&nbsp;TABLE:
</term><listitem><para>the whole table nuke_priv_msgs is deleted from the database through the DROP TABLE command.<indexterm><primary>command</primary></indexterm></para><screen><![CDATA[$db->sql_query("DROP TABLE ".$prefix."_priv_msgs");
]]></screen></listitem></varlistentry><varlistentry><term>ALTER&nbsp;TABLE:
</term><listitem><para>the structure of the nuke_users table is modified through the ALTER TABLE command:<indexterm><primary>command</primary></indexterm></para><screen><![CDATA[$db->sql_query("ALTER TABLE ".$user_prefix."_users CHANGE uname username
]]><![CDATA[VARCHAR(25) NOT NULL");
]]></screen></listitem></varlistentry><varlistentry><term>CREATE&nbsp;TABLE:
</term><listitem><para>a new table (nuke_bbforum_prune) is created through the CREATE TABLE command:<indexterm><primary>command</primary></indexterm></para><screen><![CDATA[$db->sql_query("CREATE TABLE ".$prefix."_bbforum_prune (prune_id mediumint
]]><![CDATA[(8) unsigned NOT NULL auto_increment, forum_id smallint(5) unsigned NOT NULL
]]><![CDATA[default '0', prune_days tinyint(4) unsigned NOT NULL default '0', prune_freq tinyint
]]><![CDATA[(4) unsigned NOT NULL default '0', PRIMARY KEY (prune_id), KEY forum_id
]]><![CDATA[(forum_id))");
]]></screen></listitem></varlistentry></variablelist><para>See <xref linkend="sql-syntax"> for the syntax of SQL code.</para></sect1>
</chapter>
<chapter id="move-php-nuke"><title>How to move PHP-Nuke</title><para>We discuss how to move <application>PHP-Nuke</application> from your computer to your ISP (<xref linkend="transferring-local-installation-to-web">), or from one ISP to another (<xref linkend="changing-web-hoster">). This is something that you should plan carefully. The following sections will show you how.</para><sect1 id="transferring-local-installation-to-web"><title>Transferring a local installation to the Web</title><para>You may prefer to test <application>PHP-Nuke</application> on your local box and acquaint with its features at your own pace, without the need to be constantly online. In this case, when you are done with your evaluation,<indexterm><primary>evaluation</primary></indexterm> you will face the problem of transferring your local installation to your webspace.<indexterm><primary>space</primary></indexterm> A fresh installation on the Web may not be very attractive an option to you, if you did some more or less heavy customization of the code or preferences.</para><para>For the files, simply upload the content of the html folder to your document root,<indexterm><primary>root</primary></indexterm> or wherever you want it to appear under that. For the database,<indexterm><primary>base</primary></indexterm> use mysqldump or phpMyAdmin (see <xref linkend="phpmyadmin2">) to do a backup of the database and import the data into the MySQL of your web presence. </para><para>To do a backup from the command line using mysqldump,<indexterm><primary>mysqldump</primary></indexterm> do:</para><screen><![CDATA[mysqldump -h dbhost -u dbuname -p dbname > dbbackup.sql
]]></screen><para>where dbhost,<indexterm><primary>dbhost</primary></indexterm> dbuname and dbname are exactly what you entered in config.php (see <xref linkend="config-php-file">) for these variables. To import the data using mysql from the command line, do:</para><screen><![CDATA[mysql -h dbhost -u dbuname -p dbname < dbbackup.sql
]]></screen><para>If you change your local files and/or tables regularly, you may choose to transfer only the files/tables that changed. In this case,<indexterm><primary>case</primary></indexterm> you should drop the affected tables before you reimport them. phpMyAdmin offers a convenient interface for this (see <xref linkend="phpMyAdmin-navigation-bar-SQL"> and <xref linkend="restore-single-table">). </para><para>It is a good idea to announce these measures to your community,<indexterm><primary>community</primary></indexterm> to avoid frustration among your users.</para></sect1>
<sect1 id="changing-web-hoster"><title>Changing Web hoster</title><para>Sooner or later in the life of any webmaster, the time comes for a project that most of us wished would never happen: change the hosting company! In this chapter we will take the dread out of moving your nuked site by simply outlining all the necessary steps for this operation to succeed. You will see that, although it may take some planning and foresight, it is a straightforward procedure after all. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_smile.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_smile.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_smile.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_smile.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
<para>During the whole procedure,<indexterm><primary>procedure</primary></indexterm> it is important to remember that in this case, unlike the one in <xref linkend="transferring-local-installation-to-web">, you have your users to take care of. Treat them with kindness and inform them of the coming changes, so they are prepared if something does not work as expected.</para><para>Here is the step-by-step plan to change web hoster for your PHP-Nuke:</para><orderedlist><listitem><para>Your current hoster X doesn't fit your needs anymore. You have found a better one, Y, with better conditions. But does the new hoster Y support all the functionality you need? How about</para><itemizedlist><listitem><para>Apache (version?) and modules (mod_gzip,<indexterm><primary>mod_gzip</primary></indexterm> GD library, mod_auth, mod_rewrite and all the other modules you may be using at hoster X)</para></listitem><listitem><para>PHP (version? how about <acronym>PHP</acronym> extensions?)</para></listitem><listitem><para>MySQL (version? how many databases?<indexterm><primary>databases</primary></indexterm>)</para></listitem></itemizedlist></listitem><listitem><para>You obtained the new server or webspace at hoster Y. Set the time frame for your move. A small, amateur site may need only a few days, whereas for a big, commercial<indexterm><primary>commercial</primary></indexterm> one two weeks may be more appropriate.</para></listitem><listitem><para>Ask hoster X to lower the TTL (time to live) of your domain's zone files to 900 seconds or a similar value. Normally, TTL is set to a much higher value, since DNS information does not change very often. The new, lower TTL value will force DNS servers around the world to update<indexterm><primary>date</primary></indexterm> their records about your domain in a much more frequent pace than usually. This way, changes in your domain's DNS information will propagate much faster through the Internet.<indexterm><primary>Internet</primary></indexterm></para></listitem><listitem><para>Make sure the basic &ldquo;software infrastructure<indexterm><primary>structure</primary></indexterm>&rdquo; is there on your new server (or webspace) and is working:</para><itemizedlist><listitem><para>Firewall with your custom settings (if any).</para></listitem><listitem><para>E-Mail functionality up and running</para></listitem><listitem><para>Web server configuration correct and adapted to your needs</para></listitem><listitem><para>phpMyAdmin installed and working</para></listitem></itemizedlist></listitem><listitem><para>Lock your filesystem on X and move all files from X to Y. You don't move your database on X yet, but you do move all files, even files that control access to your site, like .htaccess, hosts.allow,<indexterm><primary>hosts.allow</primary></indexterm> hosts.deny etc . files.</para></listitem><listitem><para>Do a first check using the file</para><screen><![CDATA[<?php
]]><![CDATA[phpinfo();
]]><![CDATA[?>
]]></screen><para>Put it somewhere on your new webspace, name it test.<indexterm><primary>test</primary></indexterm>php and just point your browser to it. Check that the output (file locations,<indexterm><primary>ations</primary></indexterm> configuration etc.) is what you expected.</para></listitem><listitem><para>Now it's time to move your <application>PHP-Nuke</application> database.<indexterm><primary>base</primary></indexterm> Do an announcement (see <xref linkend="administration-functions">) that you will be dumping the database,<indexterm><primary>base</primary></indexterm> then use mysqldump to dump it: </para><para>From the command line, do:</para><screen><![CDATA[mysqldump -h dbhost -u dbuname -p dbname > dbbackup.sql
]]></screen><para>where dbhost,<indexterm><primary>dbhost</primary></indexterm> dbuname and dbname are exactly what you entered in config.php (see <xref linkend="config-php-file">) for these variables.</para><para>If your database is small, say smaller than 10MB, you could try to use phpMyAdmin for the backup.<indexterm><primary>backup</primary></indexterm> But since phpMyAdmin is a <acronym>PHP</acronym> script like all the others, it is also subject<indexterm><primary>subject</primary></indexterm> to the same <acronym>CPU</acronym> time constraints (which you can see in the output of the test.<indexterm><primary>test</primary></indexterm>php file above, if you run it on hoster X). The limit is usually set to 30 seconds, which is not enough for backups<indexterm><primary>backups</primary></indexterm> of large databases.<indexterm><primary>databases</primary></indexterm> You may end up with no backup or, worse, with corrupted data.<indexterm><primary>data</primary></indexterm> But for a small site, one with a small database that is, doing the backup<indexterm><primary>backup</primary></indexterm> with phpMyAdmin is certainly an option. See <xref linkend="backup-mysql-using-browser"> for backups through the web and <xref linkend="repair-corrupt-table"> for instructions on how to repair a corrupted table or database.<indexterm><primary>base</primary></indexterm></para></listitem><listitem><para>Transfer the dbbackup.<indexterm><primary>backup</primary></indexterm>sql file to your webspace on hoster Y (you may want to compress it before you do this - compression will reduce file size and transfer time dramatically). Import the data into MySQL on Y with the command </para><screen><![CDATA[mysql -h dbhost -u dbuname -p dbname < dbbackup.sql
]]></screen><para>or using phpMyAdmin.<indexterm><primary>Admin</primary></indexterm></para></listitem><listitem><para>Test <application>PHP-Nuke</application> on Y to ensure it is working properly. Since your domain still points (through the DNS records on hoster X) to the old webspace on X, you will have to use the IP address in the URL and in the preferences (see <xref linkend="preferences">) for the tests of <application>PHP-Nuke</application> on Y.</para></listitem><listitem><para>If all looks good on Y, put a .htaccess file (see <xref linkend="htaccess-file">) in the document root on your server at X to redirect any requests to the new server at Y. That is, any requests to your domain will be re-routed to the IP of the server at Y. The following line in your .htaccess file will do this for you:</para><screen><![CDATA[redirectPermanent /oldlocation.html http://www.mynewdomain/folder/newlocation.html
]]></screen></listitem><listitem><para>Update your domain's DNS records to point to the webspace at host Y. The lower TTL setting above will take care for a rapid propagation of the new DNS information throughout the world's name servers. Changes should propagate in a few hours.</para></listitem><listitem><para>Keep your server at X for a couple of days to ensure that all DNS servers got the updated records, then cancel your services at X at your own leisure. Once you do so, you will no longer need to access Y with the IP address.</para></listitem></orderedlist><para>In case you don't have direct control over the DNS record updates,<indexterm><primary>dates</primary></indexterm> you will have to monitor your Y site closely, especially after receipt of the confirmation mail announcing to you that your application has been approved by both hosters.<indexterm><primary>hosters</primary></indexterm> You may want to write a small cron job that accesses Y by name every 5 minutes and sends you an e-mail on success. As soon as your webspace on Y is accessible by your domain name, you will know that step 11 will be completed in a few hours or, in case you couldn't change TTL,<indexterm><primary>TTL</primary></indexterm> a day.</para><para>The key idea to the above process is that you put a .htaccess file on X, redirecting from X (still accessed by domain name) to Y (accessed by IP<indexterm><primary>IP</primary></indexterm> address), as soon as you transfer the <application>PHP-Nuke</application> database to Y. See also <ulink url="http://www.nukecops.com/article-357--0-0.html">How to move a <application>PHP-Nuke</application> site</ulink>.</para></sect1>
</chapter>
<chapter id="frontend"><title>Front end structure: user view</title><para>In this chapter we will occupy ourselves, in detail, with all the functionalities implemented in PHP-Nuke, that is what our portal system can do and how. We will do this from the part of the visitor,<indexterm><primary>visitor</primary></indexterm> imagining that we are the one who visits our site and uses its functionality.<indexterm><primary>functionality</primary></indexterm> </para><para>We will analyze all the preinstalled modules in the <application>PHP-Nuke</application> distribution<indexterm><primary>distribution</primary></indexterm> and will give a look also at some very interesting modules that still have not been included in the official distribution.<indexterm><primary>distribution</primary></indexterm> We will differentiate between the 6.0 version and its successors, since there have been important changes starting from version 6.5 - the <ulink url="http://www.splatt.it">Splatt forum</ulink>, for example, has been replaced by the <ulink url="http://www.phpbb.com">phpBB f.orum</ulink>, this has created changes in other modules,<indexterm><primary>modules</primary></indexterm> like Your_Account or Private_Messages, that are now interoperating with phpBB.<indexterm><primary>phpBB</primary></indexterm></para><para>Before starting, we should spend two words on how <application>PHP-Nuke</application> is structured; this system is structured as a 3 column portal,<indexterm><primary>portal</primary></indexterm> the two lateral ones including the blocks, the central one displaying the function modules.<indexterm><primary>modules</primary></indexterm> This does not mean to say that the structure of our site cannot be modified completely. The initial skeleton is, favorably, the one to start from in order to create a super personalized portal.<indexterm><primary>portal</primary></indexterm> Beyond the 3 columns mentioned we have also a header (top of page) and a footer (bottom of page). </para><variablelist><varlistentry><term>Blocks:<indexterm><primary>Blocks</primary></indexterm>
</term><listitem><para>they are present in the left/right columns of our portal<footnote><para>In fact, a way exists to personalize the visualization of the blocks based on the page in which they are displayed to us, for example, in module news we see both the left and the right block, in module search instead, we see only the blocks on the left. </para></footnote> and deliver functions that are repeated in all pages of the site (e.g. the menu,<indexterm><primary>menu</primary></indexterm> banner and login blocks).</para></listitem></varlistentry><varlistentry><term>Modules:<indexterm><primary>Modules</primary></indexterm>
</term><listitem><para>They are the heart of the page, they appear in the center column and each one has its own function.<indexterm><primary>function</primary></indexterm> For example the news module delivers the articles, the search module makes an internal search of our site - they should be imagined as independent pages. They are the &quot;heart&quot; of the page that we visit (see <xref linkend="fig-homepage">).</para><para>
<figure id="fig-homepage">
<title>
<application>PHP-Nuke</application> Homepage
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1043;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1043;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1043;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1043;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>PHP-Nuke Homepage</phrase>
</textobject>
<caption>
<para>PHP-Nuke Homepage</para>
</caption>
</mediaobject>
</figure>
</para></listitem></varlistentry></variablelist><sect1 id="preinstalled-modules"><title>The preinstalled modules</title><variablelist><varlistentry><term>news:<indexterm><primary>news</primary></indexterm>
</term><listitem><para>Born as the heart of PHP-Nuke, it was the obligatory Home Page in previous versions. In the last versions it is instead possible to define which modules should appear as the default page.</para><para>The News module expands its branches on more pages. The first one we see is a collection of the latest News published (it is possible , from the configuration panel [admin&lyxarrow;preferences] to choose the number of latest news to be displayed, say 5, 10, 15, 20, 25, 30). In the main page only a small initial text of the news article is published. If the text is too large, it will be possible to read it whole by pressing the link &ldquo;Read more&rdquo;.</para><para>The article module has many elements that distinguish it from other ones. In the first place, the title,<indexterm><primary>title</primary></indexterm> the topic, that is the main category and is usually characterized by an image that, if clicked, brings up a selection of the articles that belong to this topic (starting from version 6.6,<indexterm><primary>6.6</primary></indexterm> it is possible to assign more than one topics to one article). We have a second way to classify the articles, which is to assign them a category they are supposed to belong (see <xref linkend="fig-category">).</para><para>
<figure id="fig-category">
<title>
Classifying articles
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1044;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1044;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1044;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1044;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Classifying articles</phrase>
</textobject>
<caption>
<para>Classifying articles</para>
</caption>
</mediaobject>
</figure>
</para><important>
<title>IMPORTANT</title>
<para>
This category is NOT a subcategory of topics, but rather a cross-sectional category that is completely independent from topics. Probably its most important function is to distinguish between "articles" and other admin-defined classes of news for which it will be possible to NOT be automatically published on the start page. "Articles" will always appear on the start news page.
</para>
</important>
<para>For example, imagine a portal that talks about soccer and it has 3 topics:<indexterm><primary>topics</primary></indexterm> </para><itemizedlist><listitem><para>League A</para></listitem><listitem><para>League B</para></listitem><listitem><para>League C</para></listitem></itemizedlist><para>We could think of cross-sectional categories like: </para><itemizedlist><listitem><para>Championship<indexterm><primary>Championship</primary></indexterm></para></listitem><listitem><para>Champions League<indexterm><primary>League</primary></indexterm></para></listitem><listitem><para>Soccer player market </para></listitem></itemizedlist><para>We can have an article that talks about League A/Championship,<indexterm><primary>Championship</primary></indexterm> or of the Soccer player market League B. Clicking o topic, say League A, we will have a selection of all the articles that talk about League A, clicking on the category,<indexterm><primary>category</primary></indexterm> Soccer player market, will have a selection of the articles that independently talk about soccer market that independently of the League being A, B or C. </para><para>At the bottom of the article we find more information about the article:<indexterm><primary>article</primary></indexterm> who inserted it, when &amp; how many times it has been read etc.</para><important>
<para>
The counter is incremented only if the "Read more" link has been clicked. The counter does not increment unless the user clicks "Read more".
</para>
</important>
<para>It displays how many more bytes are still to be read, if there have been any comments on the article and what score has been given to the article<indexterm><primary>article</primary></indexterm> by the readers. It is also possible to print the article in a printer-friendly format or you can send the link via e-mail to a friend.</para><para>Clicking on &quot; Read all &quot; brings us to the page that contains the entire article and the comments pertaining to it. In this page the user can read the entire article and interact with it through a multitude of operations.<indexterm><primary>ations</primary></indexterm></para><para>He/She can cast a vote for the article,<indexterm><primary>article</primary></indexterm> thus expressing a judgement on its validity,<indexterm><primary>validity</primary></indexterm> can comment on the article or answer to comments inserted from other users, can follow the links associated with this article,<indexterm><primary>article</primary></indexterm> display it in a printer-friendly format and send the link via e-mail to a friend. You can also attach a survey to the article.<indexterm><primary>article</primary></indexterm></para><para>In <xref linkend="modifying-PHP-Nuke-News-module"> we show how to modify the <application>PHP-Nuke</application> News module.<indexterm><primary>module</primary></indexterm></para></listitem></varlistentry><varlistentry><term>AvantGO:<indexterm><primary>AvantGO</primary></indexterm>
</term><listitem><para>It is a very simplified version of the news archive, cretated mainly from the need to visit the page via a Palm Pilot. AvantGO is a system for archiving and visualizing the pages on palmtop<indexterm><primary>palmtop</primary></indexterm> screens due to the fact the Palm Pilot has a very small screen and has a low resolution (and even a low bandwidth connection) so they require simplified pages.</para></listitem></varlistentry><varlistentry><term>Downloads&nbsp;Module:<indexterm><primary>Module</primary></indexterm>
</term><listitem><para>This module is deeply branched and is used to manage a file archive (present on our own or a third party site). It offers various modes of interaction the user (see <xref linkend="fig-downloads-admin">). </para><para>
<figure id="fig-downloads-admin">
<title>
Downloads module
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1045;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1045;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1045;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1045;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Downloads module</phrase>
</textobject>
<caption>
<para>Downloads module</para>
</caption>
</mediaobject>
</figure>
</para><para>In the main page it is possible to use an internal search engine that searches for keywords among all the files cataloged. There is also the possibility to add external links to a file (these files will not be added immediately, but put in a waiting list until an administrator<indexterm><primary>administrator</primary></indexterm> will approve them and they become visible). We can also base our selection on which files were downloaded most, or which ones obtained the highest score.<indexterm><primary>score</primary></indexterm> On this page we can have a list of categories that accompany the files (there may exist subcategories but in <xref linkend="fig-downloads-admin"> there is only 1 category,<indexterm><primary>category</primary></indexterm> &ldquo;Linux Downloads<indexterm><primary>ads</primary></indexterm>&rdquo;), the user is recognized when he/she views the downloads section after their first visit so if new downloads have been added since the last visit, the corresponding category will be have a &quot;new&quot; icon beside it.</para><para>Once we have entered the desired section, we can download the files that interest us, cast a judgment vote,<indexterm><primary>vote</primary></indexterm> report a nonexistent link to the administrator or see more information regarding the author of the file.</para><para>The file list may be ordered by insertion date,<indexterm><primary>date</primary></indexterm> judgment or popularityy (files downloaded most).</para><para>Read <xref linkend="enter-thousands-of-download-links"> if you are looking for a quick way to enter thousands of Downloads links. Further, in <xref linkend="modifying-PHP-Nuke-downloads-module"> we show how to modify the <application>PHP-Nuke</application> Downloads module.<indexterm><primary>module</primary></indexterm></para></listitem></varlistentry><varlistentry><term>Feedback:<indexterm><primary>Feedback</primary></indexterm>
</term><listitem><para>Allows the user to send feedback and contact the webmaster of the site. The user just fills in the appropriate fields which are &ldquo;Name&rdquo;, &ldquo;E-Mail&rdquo; and then the &ldquo;Message Text&rdquo;. The system will then format an e-mail message that will arrive to the webmaster<indexterm><primary>webmaster</primary></indexterm> of the site.</para></listitem></varlistentry><varlistentry><term>Member&nbsp;List:
</term><listitem><para>It displays all the users registered on the site. It is possible to select the users on the basis of their basic information<indexterm><primary>information</primary></indexterm> fields (name, nickname,<indexterm><primary>nickname</primary></indexterm> personal homepage and e-mail address). It is also possible to obtain a complete list of all the users and to order it by real name, e-mail address or homepage.<indexterm><primary>homepage</primary></indexterm></para></listitem></varlistentry><varlistentry><term>Private&nbsp;messages:
</term><listitem><para>All the registered users have access to an internal messaging system,<indexterm><primary>system</primary></indexterm> thus being able to exchange messages with each other. In the login box of each user the number of messages that are archived<indexterm><primary>archived</primary></indexterm> for this user will be displayed, and there is a management functionality<indexterm><primary>functionality</primary></indexterm> allowing for replies or deletions (see <xref linkend="fig-private-messages">).</para><para>
<figure id="fig-private-messages">
<title>
Private messages
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1046;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1046;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1046;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1046;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Private messages</phrase>
</textobject>
<caption>
<para>Private messages</para>
</caption>
</mediaobject>
</figure>
</para><para>The message that we compose has various parts:</para><itemizedlist><listitem><para>The Recipient</para></listitem><listitem><para>The Subject </para></listitem><listitem><para>The animated icon that will accompany the subject of the message</para></listitem><listitem><para>The text that can be equipped with emoticons (emotional icons) and an aid for formatting the message in HTML adding Hyperlinks, emphasized words,<indexterm><primary>words</primary></indexterm> bullet lists etc...</para></listitem></itemizedlist><para>In case there are private messages waiting for a user, this will be indicated in the login block.<indexterm><primary>block</primary></indexterm></para><para>Starting from version 6.5,<indexterm><primary>6.5</primary></indexterm> the Private Messages module has been changed: it has been integrated to the private messaging functionality of the phpBB<indexterm><primary>phpBB</primary></indexterm> forum.<indexterm><primary>forum</primary></indexterm> Sending functionality has not been changed, but there have been additions in other areas like:</para><itemizedlist><listitem><para>The list of sent messages.</para></listitem><listitem><para>The list of drafts (messages that were written, but not have not yet been sent).</para></listitem><listitem><para>The remaining space in the box containing the list of messages.</para></listitem></itemizedlist><para>The module has been integrated in a very strict fashion into the phpBB forum.<indexterm><primary>forum</primary></indexterm></para></listitem></varlistentry><varlistentry><term>Recommend&nbsp;Us:
</term><listitem><para>This module is so you can send an e-mail to a friend recommending visiting our <application>PHP-Nuke</application> site. The message that will be sent to the friend must be configured by the administrator.</para></listitem></varlistentry><varlistentry><term>Book&nbsp;Reviews<indexterm><primary>views</primary></indexterm>:
</term><listitem><para>This module serves as an archive of product/services/site reviews.<indexterm><primary>reviews</primary></indexterm> The book review must be inserted by the administrator but also from a user (a book review will need , in this case,<indexterm><primary>case</primary></indexterm> be accepted by the administrator) who, after inserting a short description of the product then may express his judgment assigning a score to it. It is also possible to insert a descriptive image. The book reviews are catalogued in alphabetical order and the selection can be made based on starting letter. </para><para>We discuss how to modify the Reviews module in <xref linkend="modifying-php-nuke-module-reviews">.</para></listitem></varlistentry><varlistentry><term>Search:
</term><listitem><para>It is the main search engine for PHP-Nuke, it does full text searches on articles, comments,<indexterm><primary>comments</primary></indexterm> sections, users and book reviews (see <xref linkend="fig-search">). It is possible to make multiple searches (e.g.. an article of a certain category written by a certain author).</para><para>
<figure id="fig-search">
<title>
Search module
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1047;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1047;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1047;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1047;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Search module</phrase>
</textobject>
<caption>
<para>Search module</para>
</caption>
</mediaobject>
</figure>
</para></listitem></varlistentry><varlistentry><term>Sections:<indexterm><primary>Sections</primary></indexterm>
</term><listitem><para>This module is a classification system parallel to the one of the topics.<indexterm><primary>topics</primary></indexterm> The classification of articles in <application>PHP-Nuke</application> does not follow a tree-like<indexterm><primary>tree-like</primary></indexterm> scheme,<indexterm><primary>scheme</primary></indexterm> as in the following example:</para><itemizedlist><listitem><para>Series A</para><itemizedlist><listitem><para>Amateur football<indexterm><primary>football</primary></indexterm></para></listitem><listitem><para>Professional football<indexterm><primary>football</primary></indexterm></para></listitem><listitem><para>Gossip<indexterm><primary>Gossip</primary></indexterm></para></listitem></itemizedlist></listitem><listitem><para>Series B</para><itemizedlist><listitem><para>Amateur football<indexterm><primary>football</primary></indexterm></para></listitem><listitem><para>Professional football<indexterm><primary>football</primary></indexterm></para></listitem><listitem><para>Gossip<indexterm><primary>Gossip</primary></indexterm></para></listitem></itemizedlist></listitem></itemizedlist><para>Instead, classification is achieved through the use of two transversal criteria,<indexterm><primary>criteria</primary></indexterm> of which one is the &ldquo;Section&rdquo; and the other one the &ldquo;Topic&rdquo;, as is better captured by a table, whose two dimensions (rows and columns) cover the two criteria (see <xref linkend="tab-sections">).</para><para><table id="tab-sections"><title>Classification with topics and sections</title><tgroup cols="4" colsep="1" rowsep="1">
<colspec colname="col0" align="left">
<colspec colname="col1" align="center">
<colspec colname="col2" align="center">
<colspec colname="col3" align="center">
<tbody>
<row>
<entry align="left" valign="top"><para></para></entry>
<entry align="center" valign="top"><para>Series A</para></entry>
<entry align="center" valign="top"><para>Series B</para></entry>
<entry align="center" valign="top"><para>Series C</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>Amateur football</para></entry>
<entry align="center" valign="top"><para>x</para></entry>
<entry align="center" valign="top"><para>x</para></entry>
<entry align="center" valign="top"><para></para></entry>
</row>
<row>
<entry align="left" valign="top"><para>Professional football</para></entry>
<entry align="center" valign="top"><para></para></entry>
<entry align="center" valign="top"><para>x</para></entry>
<entry align="center" valign="top"><para></para></entry>
</row>
<row>
<entry align="left" valign="top"><para>Gossip</para></entry>
<entry align="center" valign="top"><para></para></entry>
<entry align="center" valign="top"><para>x</para></entry>
<entry align="center" valign="top"><para>x</para></entry>
</row>
</tbody>
</tgroup></table></para><para>We discuss how to modify the Sections module in <xref linkend="modifying-PHP-Nuke-sections-module">.</para></listitem></varlistentry><varlistentry><term>Statistics:<indexterm><primary>Statistics</primary></indexterm>
</term><listitem><para>The statistics module provides basic statistical information regarding use of the site. The information varies from the total number of displayed pages , to the type of browser and operating system used, up to the number of users that are registered,<indexterm><primary>registered</primary></indexterm> the version of <application>PHP-Nuke</application> used etc.(see <xref linkend="fig-stats">).</para><para>
<figure id="fig-stats">
<title>
Statistics module
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1048;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1048;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1048;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1048;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Statistics module</phrase>
</textobject>
<caption>
<para>Statistics module</para>
</caption>
</mediaobject>
</figure>
</para></listitem></varlistentry><varlistentry><term>Stories&nbsp;archive:
</term><listitem><para>Archives all the articles by month enabling a chronological consultation. After having chosen the month, the corresponding articles are displayed with small flags besides them, visualizing the language they were written. Also in this plane it is possible to see the article in printable format<indexterm><primary>format</primary></indexterm> and to send it to a friend. An inner search engine is also comprised as well as the display of details regarding the article,<indexterm><primary>article</primary></indexterm> such as:</para><itemizedlist><listitem><para>number of comments </para></listitem><listitem><para>number of readings </para></listitem><listitem><para>score<indexterm><primary>score</primary></indexterm></para></listitem></itemizedlist><para>We discuss how to modify the Stories Archive module in <xref linkend="modifying-PHP-Nuke-stories-archive">.</para></listitem></varlistentry><varlistentry><term>Submit&nbsp;news:
</term><listitem><para>The users or the simple visitors of the site can propose to the administrator<indexterm><primary>administrator</primary></indexterm> an article that will then be examined and, if approved, published. The users do not have all the possibility of classification that the administrator does, in fact they can only decide the article's title,<indexterm><primary>title</primary></indexterm> the topic, the language and the text. They cannot classify it or choose if it should appear in the Home Page or not. And they can neither decide to publish it on a temporary basis. </para><para>We discuss how to modify the News module in <xref linkend="modifying-PHP-Nuke-News-module">.</para></listitem></varlistentry><varlistentry><term>Surveys:<indexterm><primary>Surveys</primary></indexterm>
</term><listitem><para>Enables the administrator to create a survey that will later appear in a block (<xref linkend="fig-surveys-block">) or in the survey list. The users can vote on this survey (not more than once in 24 hours), and possibly leave a comment. Moreover it is possible to display the list of the previous surveys and to consult their final results.</para></listitem></varlistentry><varlistentry><term>Top10:<indexterm><primary>Top10</primary></indexterm>
</term><listitem><para>It lists the top 10 active elements of our portal:</para><itemizedlist><listitem><para>10 most read articles</para></listitem><listitem><para>10 most commented articles</para></listitem><listitem><para>10 most active categories</para></listitem><listitem><para>10 most read articles in the special sections</para></listitem><listitem><para>10 most voted surveys<indexterm><primary>surveys</primary></indexterm></para></listitem><listitem><para>10 most active authors</para></listitem><listitem><para>10 most read book reviews<indexterm><primary>reviews</primary></indexterm></para></listitem><listitem><para>10most downloaded files</para></listitem><listitem><para>10 most read pages</para></listitem></itemizedlist></listitem></varlistentry><varlistentry><term>Topics:<indexterm><primary>Topics</primary></indexterm>
</term><listitem><para>Lists the main categories of <application>PHP-Nuke</application>. Once we have entered this module,<indexterm><primary>module</primary></indexterm> we will be able, by clicking on the corresponding icon of the topic we are interested in, to carry out a selection of articles and in automatic mode, to see all the articles corresponding to this topic. We are also presented with a small search interface to finish our search<indexterm><primary>search</primary></indexterm> in the chosen context.<indexterm><primary>context</primary></indexterm></para></listitem></varlistentry><varlistentry><term>WebLinks:<indexterm><primary>WebLinks</primary></indexterm>
</term><listitem><para>It is a collection of web links. This module has the exact same functionality as the Download module so there is no need to explain it any more. </para><para>Read <xref linkend="enter-thousands-of-web-links"> if you are looking for a quick way to enter thousands of Web links. Further, in <xref linkend="modifying-php-nuke-module-web-links"> we show how to modify the <application>PHP-Nuke</application> Web Links module.<indexterm><primary>module</primary></indexterm></para></listitem></varlistentry><varlistentry><term>Your&nbsp;Account:
</term><listitem><para>It's the administration console for your &ldquo;User Profile&rdquo; (It only works for registered users), the implemented functions are (see <xref linkend="fig-your-account">):</para><itemizedlist><listitem><para>Change your info:<indexterm><primary>info</primary></indexterm> enables management of your profile by changing your E-mail, Where you're from, AIM, ICQ,<indexterm><primary>ICQ</primary></indexterm> Avatar &amp; Fake E-mail etc...</para></listitem><listitem><para>Change your Home: creates a personalized menu (as a block) for navigation,<indexterm><primary>navigation</primary></indexterm> the user can put in there whatever he wants (tests,<indexterm><primary>tests</primary></indexterm> links, images).</para></listitem><listitem><para>Setup comments:<indexterm><primary>comments</primary></indexterm> Configures the display of comments, assigning display criteria.</para></listitem><listitem><para>Theme selection: Changes the theme of the site, allowing you to choose between all available themes.<indexterm><primary>themes</primary></indexterm></para></listitem><listitem><para>Journal:<indexterm><primary>Journal</primary></indexterm> enables you to write your own diary to be published on the portal. Something like a Weblog in a Weblog,<indexterm><primary>Weblog</primary></indexterm> so to say. ;-)</para></listitem><listitem><para>Webmail:<indexterm><primary>Webmail</primary></indexterm> once configured correctly, this mail application allows you to read all your e-mails from all your e-mail accounts, without the need for any other mail client.</para></listitem><listitem><para>Logout/Exit: It lets us exit from our current user profile,<indexterm><primary>profile</primary></indexterm> cancelling the cookie.<indexterm><primary>cookie</primary></indexterm></para></listitem><listitem><para>My Headlines: Imports into the user's private area those news in RDF/RSS<indexterm><primary>RSS</primary></indexterm> format that are published by preselected news sources.<indexterm><primary>sources</primary></indexterm> The user can thus set up together his own personalized newspaper.<indexterm><primary>newspaper</primary></indexterm> An even broader news functionality is offered by the My Headlines module<indexterm><primary>module</primary></indexterm> (<xref linkend="PHP-Nuke-My-Headlines-module">), whose functionality you can see in action at Chris' <ulink url="http://www.karakas-online.de/myHeadlines/">News-o-matic</ulink> page.</para></listitem><listitem><para>Broadcast Message: If the subject is aproppriate and the administrator has allowed it in the Preferences of the administration panel (<xref linkend="backend">), we can send messages that will be visible to all users on the home page of the site. It is also possible to disable the function,<indexterm><primary>function</primary></indexterm> so that we don't see messages broadcast by other users.</para></listitem><listitem><para>Your private messages: This box displays the user's private messages.</para></listitem><listitem><para>Last 10 articles: Offers a list of the last 10 articles posted by that user.
</para></listitem></itemizedlist><para>
<figure id="fig-your-account">
<title>
Your account
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1049;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1049;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1049;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1049;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Your account</phrase>
</textobject>
<caption>
<para>Your account</para>
</caption>
</mediaobject>
</figure>
</para><para>We then have a main menu that informs us of how many and which comments<indexterm><primary>comments</primary></indexterm> we have inserted and how many stories we have published.</para><para>In <xref linkend="modifying-php-nuke-moduke-your-account"> we show how to modify the <application>PHP-Nuke</application> Your Account module.<indexterm><primary>module</primary></indexterm> If you are looking for a module that extends the possibilities of the standard Your Account module,<indexterm><primary>module</primary></indexterm> have a look at the Your Account Tweak module in <xref linkend="NSN-Your-Account-Tweak-module"> and the Approve Membership module in <xref linkend="PHP-Nuke-Approve-Membership-module">.</para></listitem></varlistentry><varlistentry><term>Content:<indexterm><primary>Content</primary></indexterm>
</term><listitem><para>This is a module that allows you to create your pages just as you prefer: you can insert HTML code (even one created by those very ugly visual editors) and it will be incorporated into the look and feel of your theme<indexterm><primary>theme</primary></indexterm> when the article is displayed. </para><para>The Content module posesses a series of fields. Some are displayed only in the first page, some others only in the last one. The &ldquo;Page Header<indexterm><primary>Header</primary></indexterm>&rdquo; field is the principal one, it is possible to separate the content into subpages, inserting at the aproppriate places in the text the &lt;!--pagebreak&gt; tag. For example, if you write</para><screen><![CDATA[My Homepage is the best website
]]><![CDATA[<!--pagebreak>
]]><![CDATA[I visit it every day
]]></screen><para>then the text &ldquo;I visit it every day&rdquo; will be on the second page. See also <xref linkend="include-HTML-file-in-module">, <xref linkend="include-HTML-file-and-links-in-module"> and <xref linkend="include-HTML-file-and-links-in-module-iframe"> for other techniques to incorporate HTML content in <application>PHP-Nuke</application>.</para></listitem></varlistentry><varlistentry><term>Encyclopedia:
</term><listitem><para>It is a system for creating one or more word dictionaries.<indexterm><primary>dictionaries</primary></indexterm> In the first selection scheme it requires you to enter the dictionary (displaying even a small flag that indicates the language), after the click we are invited to choose the letter that corresponds to the searched word or to use the inner search engine of the encyclopedia,<indexterm><primary>encyclopedia</primary></indexterm> once found it's enough to click on the word to discover its meaning.</para><para>In <xref linkend="make-encyclopedia-international">, you can read how to internationalize the Encyclopedia module.<indexterm><primary>module</primary></indexterm> You can also use the Random Quotes block (<xref linkend="PHP-Nuke-Random-Quotes-block">) to create a random encyclopedia.<indexterm><primary>encyclopedia</primary></indexterm></para></listitem></varlistentry><varlistentry><term>FAQ:<indexterm><primary>FAQ</primary></indexterm>
</term><listitem><para>It is an archive of Questions/Answers divided by category that can be consulted by the user as a first solution to his problems. He can divide the Questions/Answers by category in order to facilitate the consultation.</para><para>If you want to display HTML code in a FAQ,<indexterm><primary>FAQ</primary></indexterm> have a look at <xref linkend="display-html-code-in-faq">. See also <xref linkend="duplicating-PHP-Nuke-FAQ-module"> if you want to duplicate the FAQ module.<indexterm><primary>module</primary></indexterm></para></listitem></varlistentry><varlistentry><term>Splatt&nbsp;Forum:<indexterm><primary>Forum</primary></indexterm>
</term><listitem><para>(note: the Splatt forum is included in <application>PHP-Nuke</application> version 6.0, but not in the successive ones, where it was replaced by the phpBB Forum,<indexterm><primary>Forum</primary></indexterm> to be described subsequently). </para><para>The functionalities implemented in this forum (on the user side) are many (see <xref linkend="fig-splatt-forum">), the forums are divided by category, have a dedicated inner search engine,<indexterm><primary>engine</primary></indexterm> users can associate to every post (participation in the forum) icons relating to the argument, cast a vote on a discussion, see various icons according to the degree of attention degree that a specific discussion has generated, see how many questions and answers a certain thread has received, see the profile of that user and many other functions.</para><para>
<figure id="fig-splatt-forum">
<title>
Splatt Forum.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1050;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1050;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1050;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1050;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Splatt Forum.</phrase>
</textobject>
<caption>
<para>Splatt Forum.</para>
</caption>
</mediaobject>
</figure>
</para></listitem></varlistentry><varlistentry><term>phpBB&nbsp;Forum:<indexterm><primary>Forum</primary></indexterm>
</term><listitem><para>This Forum module is installed in <application>PHP-Nuke</application> starting from version 6.5,<indexterm><primary>6.5</primary></indexterm> replacing the Splatt Forum (<xref linkend="fig-phpbb-forum">). It offers a series of additional features,<indexterm><primary>features</primary></indexterm> like an optimal search functionality for threads or an optimal user profile management,<indexterm><primary>management</primary></indexterm> where it is now possible to insert alerts to inform a user via e-mail of the arrival of a response<indexterm><primary>response</primary></indexterm> to a posting or private message of his.</para><para>Among the novelties in the forum interface is a list of the users currently online, an interface for the formatting of the inserted text, the possibility to attach a survey to every thread etc. </para><para>
<figure id="fig-phpbb-forum">
<title>
phpBB Forum.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1051;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1051;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1051;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1051;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>phpBB Forum.</phrase>
</textobject>
<caption>
<para>phpBB Forum.</para>
</caption>
</mediaobject>
</figure>
</para></listitem></varlistentry><varlistentry><term>XDMP:<indexterm><primary>XDMP</primary></indexterm>
</term><listitem><para>Starting from version 6.8 of PHP-Nuke, it is possible to acquire News from the <ulink url="http://xdmp.com">XDMP site</ulink>. The News are available in many categories and will be automatically published on your site, once you acquire the service. For this to take place, you will only need to edit the modules/News/xdmp.php file, inserting the login and password you were assigned on acquisition.<indexterm><primary>acquisition</primary></indexterm> You can set up the news categories and the refresh intervalls from the interface offered by modules/News/xdmp.php. An even broader news functionality is offered by the My Headlines module<indexterm><primary>module</primary></indexterm> (<xref linkend="PHP-Nuke-My-Headlines-module">), whose functionality you can see in action at Chris' <ulink url="http://www.karakas-online.de/myHeadlines/index.html">News-o-matic</ulink> page.</para></listitem></varlistentry></variablelist></sect1>
<sect1 id="non-installed-modules"><title>Non-installed modules</title><para>See <xref linkend="PHP-Nuke-add-on-modules"> for some interesting add-on modules for <application>PHP-Nuke</application>.</para></sect1>
<sect1 id="preinstalled-blocks"><title>The preinstalled blocks</title><variablelist><varlistentry><term>Modules:
</term><listitem><para>Lists all active modules.<indexterm><primary>modules</primary></indexterm> In case you are the Administrator, it displays also the inactive modules,<indexterm><primary>modules</primary></indexterm> as wel as those that are hidden. The Modules block is very often used for navigation purposes, see for example <xref linkend="PHP-Nuke-Menu-Builder">, <xref linkend="PHP-Nuke-Treemenu-with-PHP">, <xref linkend="PHP-Nuke-Treemenu-with-Javascript"> and <xref linkend="build-custom-module-blocks">. But it is also possible to use the Content block (see below) to obtain a similar result.</para><para>
<figure id="fig-modules-block-3">
<title>
The standard Modules block
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1052;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1052;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1052;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1052;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase> The standard Modules block</phrase>
</textobject>
<caption>
<para> The standard Modules block</para>
</caption>
</mediaobject>
</figure>
</para></listitem></varlistentry><varlistentry><term>Administration:<indexterm><primary>Administration</primary></indexterm>
</term><listitem><para>Lists the links that lead to the administration area. It is divided into two blocks, one that lists shortcuts to some administration<indexterm><primary>administration</primary></indexterm> functions, and another that lists links to content awaiting approval (<xref linkend="fig-waiting-content-block-2">, or to reports of problems like broken links, broken downloads etc.</para><para>
<figure id="fig-waiting-content-block-2">
<title>
Waiting Content block.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1053;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1053;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1053;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1053;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Waiting Content block.</phrase>
</textobject>
<caption>
<para>Waiting Content block.</para>
</caption>
</mediaobject>
</figure>
</para></listitem></varlistentry><varlistentry><term>Who&nbsp;is&nbsp;online:
</term><listitem><para>Lists the number of users that are online at the moment (<xref linkend="fig-who-is-online">).</para><para>
<figure id="fig-who-is-online">
<title>
Who Is Online block.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1054;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1054;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1054;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1054;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Who Is Online block.</phrase>
</textobject>
<caption>
<para>Who Is Online block.</para>
</caption>
</mediaobject>
</figure>
</para></listitem></varlistentry><varlistentry><term>Search:
</term><listitem><para>Search block for the contents of the site.</para></listitem></varlistentry><varlistentry><term>Languages:
</term><listitem><para>Allows you to change the language of the <application>PHP-Nuke</application> interface.<indexterm><primary>interface</primary></indexterm> In the Preferences of the administration panel (<xref linkend="backend">), you can select whether the block shall display flag icons (<xref linkend="fig-languages">) or a drop-down list for the language selection.</para><para>
<figure id="fig-languages">
<title>
Languages block.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1055;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1055;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1055;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1055;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Languages block.</phrase>
</textobject>
<caption>
<para>Languages block.</para>
</caption>
</mediaobject>
</figure>
</para></listitem></varlistentry><varlistentry><term>Random&nbsp;Headlines:
</term><listitem><para>Displays random phrases in a block.<indexterm><primary>block</primary></indexterm> See also the Random Quotes block in <xref linkend="PHP-Nuke-Random-Quotes-block">.</para></listitem></varlistentry><varlistentry><term>User's&nbsp;custom&nbsp;box:
</term><listitem><para>A block where the user can have whatever he likes. The contents of the block will solely be visible to the user who created it.</para></listitem></varlistentry><varlistentry><term>Categories&nbsp;Menu:
</term><listitem><para>Displays the available categories as links.</para></listitem></varlistentry><varlistentry><term>Survey:<indexterm><primary>Survey</primary></indexterm>
</term><listitem><para>Displays the current survey in the block (<xref linkend="fig-surveys-block">).</para><para>
<figure id="fig-surveys-block">
<title>
Surveys block.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1056;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1056;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1056;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1056;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Surveys block.</phrase>
</textobject>
<caption>
<para>Surveys block.</para>
</caption>
</mediaobject>
</figure>
</para></listitem></varlistentry><varlistentry><term>Login:
</term><listitem><para>A block where the registered user can enter his nickname and password<indexterm><primary>password</primary></indexterm> in order to be recognized as such and be granted access to the services<indexterm><primary>services</primary></indexterm> of the site that are restricted to registered users only (<xref linkend="fig-login">). See <xref linkend="create-logout-module"> for a logout module.<indexterm><primary>module</primary></indexterm></para><para>
<figure id="fig-login">
<title>
Login block.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1057;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1057;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1057;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1057;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Login block.</phrase>
</textobject>
<caption>
<para>Login block.</para>
</caption>
</mediaobject>
</figure>
</para></listitem></varlistentry><varlistentry><term>Big&nbsp;Story&nbsp;of&nbsp;Today:
</term><listitem><para>Displays the most read story of today in the block.<indexterm><primary>block</primary></indexterm></para></listitem></varlistentry><varlistentry><term>Old&nbsp;Articles:<indexterm><primary>Articles</primary></indexterm>
</term><listitem><para>Lists old articles that are not shown in the central News column anymore.</para></listitem></varlistentry><varlistentry><term>Advertising&nbsp;Block<indexterm><primary>lock</primary></indexterm>:
</term><listitem><para>From this release on we have the possibility to insert our banners also in the blocks (buttons various of dimensions) being managed as if it were our own circuiting banner,<indexterm><primary>banner</primary></indexterm> counting clicks, impressions etc. See <xref linkend="advertisements-in-php-nuke-blocks">, for advertisements in <application>PHP-Nuke</application> blocks and <xref linkend="advertisements-in-php-nuke-modules">, for advertisements in <application>PHP-Nuke</application> modules.<indexterm><primary>modules</primary></indexterm> For Google ads,<indexterm><primary>ads</primary></indexterm> you can also use the Google AdSense block of <xref linkend="PHP-Nuke-Google-AdSense-block">.</para></listitem></varlistentry><varlistentry><term>Content:<indexterm><primary>Content</primary></indexterm>
</term><listitem><para>Displays the most active content. See <xref linkend="Simple-Content-block"> for instructions on how to make a simple Content block yourself.</para></listitem></varlistentry><varlistentry><term>Encyclopedia:<indexterm><primary>Encyclopedia</primary></indexterm>
</term><listitem><para>lists all active encyclopedias, clicking the link will bring us directly inside the list of terms of the chosen encyclopedia.<indexterm><primary>encyclopedia</primary></indexterm></para><para>In <xref linkend="make-encyclopedia-international">, you can read how to internationalize the Encyclopedia module.<indexterm><primary>module</primary></indexterm> You can also use the Random Quotes block (<xref linkend="PHP-Nuke-Random-Quotes-block">) to create a random encyclopedia.<indexterm><primary>encyclopedia</primary></indexterm></para></listitem></varlistentry><varlistentry><term>Forums:
</term><listitem><para>The forums block lists the last 10 posted messages and a search<indexterm><primary>search</primary></indexterm> engine that executes a query on all the posts of the forum.<indexterm><primary>forum</primary></indexterm></para></listitem></varlistentry><varlistentry><term>Last&nbsp;5&nbsp;articles:
</term><listitem><para>It lists the last 5 published articles offering information on how many readings and how many comments have been made.</para></listitem></varlistentry><varlistentry><term>Last&nbsp;10&nbsp;referers<indexterm><primary>referers</primary></indexterm>:
</term><listitem><para>It lists the sites from which the last 10 visits have arrived.</para></listitem></varlistentry><varlistentry><term>Ephemerids:<indexterm><primary>Ephemerids</primary></indexterm>
</term><listitem><para>It is a block that manages the recurrent events. It lists the events happened on the same date but in the previous years. Read <xref linkend="enter-thousands-of-ephemerids"> if you are looking for a quick way to enter thousands of ephemerids.<indexterm><primary>ephemerids</primary></indexterm></para></listitem></varlistentry><varlistentry><term>Reviews:<indexterm><primary>Reviews</primary></indexterm>
</term><listitem><para>It lists in a block the book reviews of the day. We discuss how to modify the Reviews module in <xref linkend="modifying-php-nuke-module-reviews">.</para></listitem></varlistentry><varlistentry><term>Sections<indexterm><primary>Sections</primary></indexterm>&nbsp;Articles<indexterm><primary>Articles</primary></indexterm>:
</term><listitem><para>lists the active sections. Clicking one we will get to the corresponding article list. We discuss how to modify the Sections module in <xref linkend="modifying-PHP-Nuke-sections-module">.</para></listitem></varlistentry><varlistentry><term>Top&nbsp;10&nbsp;Downloads<indexterm><primary>ads</primary></indexterm>:
</term><listitem><para>It lists the 10 most downloaded files. Read <xref linkend="enter-thousands-of-download-links"> if you are looking for a quick way to enter thousands of Downloads links. Further, in <xref linkend="modifying-PHP-Nuke-downloads-module"> we show how to modify the <application>PHP-Nuke</application> Downloads module.<indexterm><primary>module</primary></indexterm></para></listitem></varlistentry><varlistentry><term>Top&nbsp;10&nbsp;Links:
</term><listitem><para>It lists the 10 most clicked links in the archives.<indexterm><primary>archives</primary></indexterm></para></listitem></varlistentry></variablelist></sect1>
</chapter>
<chapter id="backend"><title>Back end structure: administrator view</title><para>The administration page is reached by calling the page admin.<indexterm><primary>admin</primary></indexterm>php (www.yoursite.com/admin.php) and carrying out the login procedure inserting your user and password.<indexterm><primary>password</primary></indexterm> (Remember that the normal users should not login from the page admin.php<indexterm><primary>admin.php</primary></indexterm> but from the appropriate module). Starting from version 6.5,<indexterm><primary>6.5</primary></indexterm> one has also to type a security code in an extra field. The security code is chosen randomly each time and must be the same as the one displayed in a graphic and is &ldquo;poisoned<indexterm><primary>poisoned</primary></indexterm>&rdquo; with &ldquo;noise<indexterm><primary>noise</primary></indexterm>&rdquo; to make automatic number recognition by login scripts impossible (see the <ulink url="http://mil-sim.net/modules.php?name=Downloads&amp;op=getit&amp;lid=21">Electric Dice</ulink> site for more information on the difficulties of creating truly random<indexterm><primary>random</primary></indexterm> numbers and poisoned images).</para><para>Once logged in, the administrator finds an interface that lists all the areas which can be acted upon (see <xref linkend="fig-admin-panel">). If the administrator is a superadmin,<indexterm><primary>superadmin</primary></indexterm> he may work on all the areas of the site, if instead he is an administrator with limited powers he will see the links relative to the areas on which he is allowed to work. Through the preferences configuration we will be able to decide whether to display icons or just a textual interface.<indexterm><primary>interface</primary></indexterm> Depending on our choice, either a textual or an icon administration interface<indexterm><primary>interface</primary></indexterm> will appear. <xref linkend="fig-admin-panel"> shows the icon interface.<indexterm><primary>interface</primary></indexterm> Note that the icons of the admin panel are theme dependent.</para><para>
<figure id="fig-admin-panel">
<title>
Administration panel.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1058;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1058;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1058;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1058;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel.</phrase>
</textobject>
<caption>
<para>Administration panel.</para>
</caption>
</mediaobject>
</figure>
</para><para>Remember that when you write new administration modules you must also create the corresponding icon, otherwise, when in visual administration mode, only the textual link corresponding to your module will appear and you won't be able to click it.</para><para>In order to set up the graphical administration mode you must go to the preferences section and set up in &quot;graphical options&quot; the &ldquo;graphical menu in administration<indexterm><primary>administration</primary></indexterm>&rdquo; option to &ldquo;yes&rdquo;.</para><sect1 id="administration-functions"><title>The administration functions</title><para>
<figure id="fig-stories">
<title>
Administration panel: Add story.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1059;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1059;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1059;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1059;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Add story.</phrase>
</textobject>
<caption>
<para>Administration panel: Add story.</para>
</caption>
</mediaobject>
</figure>
</para><variablelist><varlistentry><term>Add&nbsp;Story:
</term><listitem><para>It is the function that adds a new article to the News module.<indexterm><primary>module</primary></indexterm> (We discuss how to modify the News module in <xref linkend="modifying-PHP-Nuke-News-module">.) The options offered are many and will be analyzed here one by one <footnote><para>Note that, starting from version 6.7, a news article may be associated with multiple topics.</para></footnote>:</para><itemizedlist><listitem><para>Title: inserts the news title.<indexterm><primary>title</primary></indexterm></para></listitem><listitem><para>Topic: Determines which Topic will be associated with the article.<indexterm><primary>article</primary></indexterm></para></listitem><listitem><para>Category:Determines which Category will be associated with the article.<indexterm><primary>article</primary></indexterm></para></listitem><listitem><para>Publish in the Homepage: if this option is not selected, then the article<indexterm><primary>article</primary></indexterm> will be displayed only in the topics or the relative categories and not in the main page of the news module .</para></listitem><listitem><para>Activate comments:<indexterm><primary>comments</primary></indexterm> If it's not activated the users cannot comment on the article.<indexterm><primary>article</primary></indexterm></para></listitem><listitem><para>Language:<indexterm><primary>Language</primary></indexterm> If in the preferences we have activated the multilingual option, we will be asked in which language we will publish the article.<indexterm><primary>article</primary></indexterm> (e.g. if I publish an article in english, I will see it displayed only if I click<indexterm><primary>click</primary></indexterm> on the small english flag in the languages block and so on...).</para></listitem><listitem><para>Story Text: It is the text that appears in the preview.<indexterm><primary>preview</primary></indexterm></para></listitem><listitem><para>Extended Text: It is the text that appears when we click on &quot;read all&quot;.</para></listitem><listitem><para>Programmed article:<indexterm><primary>article</primary></indexterm> The administrator is given the ability to choose when the article should be published, deciding on the publishing date and hour. It is not a neccesary function but it is very useful.</para></listitem><listitem><para>Preview or send: Depending on the choice made here determines whether the article will be displayed in preview mode or directly published.</para></listitem><listitem><para>Survey:<indexterm><primary>Survey</primary></indexterm> It is possible to attach a survey to a specific article (<xref linkend="fig-article-poll">).</para><para>
<figure id="fig-article-poll">
<title>
Attaching a poll to an article awaiting admission.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1060;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1060;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1060;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1060;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Attaching a poll to an article awaiting admission.</phrase>
</textobject>
<caption>
<para>Attaching a poll to an article awaiting admission.</para>
</caption>
</mediaobject>
</figure>
</para><para>In the case that this option is activated,<indexterm><primary>activated</primary></indexterm> when the reader clicks on &quot;read all&quot;, a survey block will appear that is different from the survey block<indexterm><primary>block</primary></indexterm> on the home page. We thus have two survey blocks active:</para><orderedlist><listitem><para><indexterm><primary>Enumerate</primary></indexterm>The survey block on the home page (<xref linkend="fig-surveys-block">).</para></listitem><listitem><para><indexterm><primary>Enumerate</primary></indexterm>The survey block attached to the specific article (<xref linkend="fig-article-poll-block">).</para></listitem></orderedlist><para>
<figure id="fig-article-poll-block">
<title>
Article Poll block.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1061;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1061;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1061;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1061;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Article Poll block.</phrase>
</textobject>
<caption>
<para>Article Poll block.</para>
</caption>
</mediaobject>
</figure>
</para></listitem></itemizedlist></listitem></varlistentry></variablelist><para>
<figure id="fig-backup">
<title>
Administration panel: Backup DB.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1062;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1062;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1062;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1062;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Backup DB.</phrase>
</textobject>
<caption>
<para>Administration panel: Backup DB.</para>
</caption>
</mediaobject>
</figure>
</para><variablelist><varlistentry><term>Backup&nbsp;DB:
</term><listitem><para>It is the function that allows us to create a backup file that contains both structure and content of the <application>PHP-Nuke</application> database.<indexterm><primary>base</primary></indexterm> This is very useful in case our data gets lost. </para><para>Once we click on &ldquo;Backup DB<indexterm><primary>Backup DB</primary></indexterm>&rdquo;, we will have to wait for the server to create the file. Waiting time varies from a few seconds to some minutes in the case of a large database.<indexterm><primary>base</primary></indexterm> Once created, we will be asked to download the file. Remember to keep your backup in a safe place! See <xref linkend="backup-mysql-using-browser"> for other backup solutions.</para></listitem></varlistentry></variablelist><para>
<figure id="fig-banners">
<title>
Administration panel: Banners.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1063;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1063;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1063;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1063;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Banners.</phrase>
</textobject>
<caption>
<para>Administration panel: Banners.</para>
</caption>
</mediaobject>
</figure>
</para><variablelist><varlistentry><term>Banners:
</term><listitem><para>You can manage your advertising strategy with this function:<indexterm><primary>function</primary></indexterm> you can add clients,<indexterm><primary>clients</primary></indexterm> then add banners images for each client. The banners will be displayed at the top of the page, before the header<indexterm><primary>header</primary></indexterm> (if you want to change banner placement, see <xref linkend="PHP-Nuke-header-change-banner-placement">). You can control the number of impressions per banner and you can also gather statistics on the achieved views and clicks.</para><para>See also <xref linkend="advertisements-in-php-nuke-blocks">, for advertisements in <application>PHP-Nuke</application> blocks and <xref linkend="advertisements-in-php-nuke-modules">, for advertisements in <application>PHP-Nuke</application> modules.<indexterm><primary>modules</primary></indexterm> For Google ads,<indexterm><primary>ads</primary></indexterm> you can also use the Google AdSense block of <xref linkend="PHP-Nuke-Google-AdSense-block">.</para></listitem></varlistentry></variablelist><para>
<figure id="fig-blocks">
<title>
Administration panel: Blocks.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1064;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1064;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1064;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1064;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Blocks.</phrase>
</textobject>
<caption>
<para>Administration panel: Blocks.</para>
</caption>
</mediaobject>
</figure>
</para><variablelist><varlistentry><term>Blocks<indexterm><primary>Blocks</primary></indexterm>:
</term><listitem><para>It's a very important function because it allows us to control the left and right columns of our portal.<indexterm><primary>portal</primary></indexterm> The scheme is presented with a list of the blocks that we have created, we can then activate,<indexterm><primary>activate</primary></indexterm> deactivate or edit them changing their position and order and assigning them permissions.<indexterm><primary>permissions</primary></indexterm> We can in fact decide if a block should be visible by all, only by the registered users, or only the administrator.<indexterm><primary>administrator</primary></indexterm> We can also make the block visible only in a specific language.</para><note>
<title> Please note</title>
<para>
This info is also present in <xref linkend="blocks">
</para>
</note>
<para>The <application>PHP-Nuke</application> blocks can be of 3 different types:</para><itemizedlist><listitem><para>RSS/RDF:<indexterm><primary>RDF</primary></indexterm> These are blocks that capture news put at our disposal from other sites. The files are in a standard format,<indexterm><primary>format</primary></indexterm> suitable for reading the text contained in them (for example, the site <ulink url="http://www.spaghettibrain.com">Spaghettibrain.com</ulink> is a site that feeds news to other sites).</para><para>RSS is a protocol, an application of XML,<indexterm><primary>XML</primary></indexterm> that provides an open method of syndicating and aggregating Web content. Using RSS files, you can create a data feed that supplies headlines,<indexterm><primary>headlines</primary></indexterm> links, and article summaries from your Web site. This function is done automatically by the backend.<indexterm><primary>backend</primary></indexterm>php file of your <application>PHP-Nuke</application> system,<indexterm><primary>system</primary></indexterm> so that other sites that wish to display (we say &ldquo;syndicate<indexterm><primary>syndicate</primary></indexterm>&rdquo; in this context) news from your site, only have to enter the address &ldquo;http://www.yoursite.com/backend.php<indexterm><primary>backend.php</primary></indexterm>&rdquo; . For more information on RSS,<indexterm><primary>RSS</primary></indexterm> see this <ulink url="http://gils.utah.gov/rss/">RSS Workshop</ulink>.</para></listitem><listitem><para>Blocks of content: They are blocks which we insert simple HTML or text that will be displayed inside the block (see the following example)</para></listitem><listitem><para>Blocks of files: They are <acronym>PHP</acronym> scripts that execute predetermined commands (see the following paragraph)</para></listitem></itemizedlist><para>In order to create a new block that will be added to the list of available blocks, we must scroll down the page and position ourselves on &quot;add block&quot;. </para><para>The title field is a common element for all and will be compiled in.</para><itemizedlist><listitem><para>If we want to create a RSS/RDF block we must choose the news source from the available list or add one by clicking on &ldquo;setup<indexterm><primary>setup</primary></indexterm>&rdquo;. In this case we will supply the address of the file to read (this info<indexterm><primary>info</primary></indexterm> generally will be supplied by the webmaster of the site from which we capture<indexterm><primary>capture</primary></indexterm> the news,<indexterm><primary>news</primary></indexterm> or, if it is a site created with PHP-Nuke, simply by asking for the file backend.<indexterm><primary>backend</primary></indexterm>php of that site). The other fields will all be compiled in with the exception of &ldquo;filename<indexterm><primary>filename</primary></indexterm>&rdquo; and &ldquo;Content<indexterm><primary>Content</primary></indexterm>&rdquo;. There is a bug that will display a message, saying &ldquo;There is a current problem with the headlines from this site.&rdquo;, although everything will be set up right, see <xref linkend="build-rss-blocks-with-variable-news-number">. </para></listitem><listitem><para>If we want to create a block of simple text instead, we will omit the field &ldquo;RSS/RDF file URL<indexterm><primary>URL</primary></indexterm>&rdquo; and will complete &ldquo;Content<indexterm><primary>Content</primary></indexterm>&rdquo; instead (Omitting &rdquo;filename<indexterm><primary>filename</primary></indexterm>&rdquo;).</para></listitem><listitem><para>If instead we want to include the <acronym>PHP</acronym> files that interface with a database<indexterm><primary>base</primary></indexterm> or perform particular functions, then we will omit &ldquo;Content<indexterm><primary>Content</primary></indexterm>&rdquo; and &ldquo;RSS/RDF<indexterm><primary>RDF</primary></indexterm>&rdquo; and will choose between the available files the one that will create our block.<indexterm><primary>block</primary></indexterm> (If you want more info on how to create blocks, see <xref linkend="blocks">). Just choose the block from the drop-down list of available blocks and set a title for it (or leave the title untouched).</para></listitem></itemizedlist><para>Remember that before publishing a block,<indexterm><primary>block</primary></indexterm> we will be shown a preview of it.</para><tip>
<title> Use custom blocks for building navigation menus</title>
<para>
Many users think that the Modules block (<xref linkend="fig-modules-block">) is the obligatory way of building a navigation menu. However, it is just as possible to create custom blocks containing our HTML code and images or links - see <xref linkend="build-custom-module-blocks"> for various approaches in this direction.
</para>
</tip>
<para>Finally, the block can be positioned</para><itemizedlist><listitem><para>in the left/right column, or</para></listitem><listitem><para>in the central column, either at the top or at the bottom.</para></listitem></itemizedlist><para>You can change the relative positioning of all the blocks inside a column by clicking on the up and down arrows in the table that lists all blocks in the blocks administration panel.<indexterm><primary>panel</primary></indexterm></para><para>See <xref linkend="php-nuke-add-on-blocks"> for interesting add-on blocks.</para></listitem></varlistentry></variablelist><para>
<figure id="fig-content">
<title>
Administration panel: Content.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1065;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1065;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1065;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1065;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Content.</phrase>
</textobject>
<caption>
<para>Administration panel: Content.</para>
</caption>
</mediaobject>
</figure>
</para><variablelist><varlistentry><term>Content<indexterm><primary>Content</primary></indexterm>&nbsp;Manager:
</term><listitem><para>This function allows us to add new categories and new content inside the content section. Think of it as a container for creating empty pages. A noteworthy feature is the possibility to add the tag</para><screen><![CDATA[<! -- pagebreak -- >
]]></screen><para>in order to create a multipage article.<indexterm><primary>article</primary></indexterm> The elements that comprise the Content module are:</para><itemizedlist><listitem><para>title,<indexterm><primary>title</primary></indexterm></para></listitem><listitem><para>subtitle,<indexterm><primary>title</primary></indexterm></para></listitem><listitem><para>page header text,</para></listitem><listitem><para>page main text,</para></listitem><listitem><para>page footer text,</para></listitem><listitem><para>signature.<indexterm><primary>nature</primary></indexterm></para></listitem></itemizedlist><para>The </para><screen><![CDATA[<! -- pagebreak -- >
]]></screen><para>function is only active in the page main text field.</para><para>After you have created the desired categories you can then go to http://yoursite.com/admin.php?<indexterm><primary>admin.php</primary></indexterm>op=content and start adding pages to the categories. </para><para>You can create links that point directly to the pages created by the Content<indexterm><primary>Content</primary></indexterm> module and use them in menus or buttons. The links could look as follows:</para><screen><![CDATA[modules.php?name=Content&pa=showpage&pid=1
]]></screen><para>where pid=1 is the page <acronym>ID</acronym> that uniquely identifies the Content page.</para><para>An easy way to find out the correct URL to use in links to Content pages, is to click on the Content link in the modules block,<indexterm><primary>block</primary></indexterm> view each page and copy its URL from the browser's address window. You can then just add these URLs to a HTML block,<indexterm><primary>block</primary></indexterm> maybe like this: </para><screen><![CDATA[&nbsp;&nbsp;<b><big>&middot;</big></b>
]]><![CDATA[<img src=images/blocks/icon_dot.gif>&nbsp;
]]><![CDATA[<a href="modules.php?name=Content&pa=showpage&pid=1">
]]><![CDATA[Page Title 1</a><BR>
]]><![CDATA[
]]><![CDATA[&nbsp;&nbsp;<b><big>&middot;</big></b>
]]><![CDATA[<img src=images/blocks/icon_dot.gif>&nbsp;
]]><![CDATA[<a href="modules.php?name=Content&pa=showpage&pid=2">
]]><![CDATA[Page Title 2</a><BR>
]]><![CDATA[
]]><![CDATA[&nbsp;&nbsp;<b><big>&middot;</big></b>
]]><![CDATA[<img src=images/blocks/icon_dot.gif>&nbsp;
]]><![CDATA[<a href="modules.php?name=Content&pa=showpage&pid=3">
]]><![CDATA[Page Title 3</a><BR>
]]></screen><para>and so on. See also <xref linkend="include-HTML-file-in-module">, <xref linkend="include-HTML-file-and-links-in-module"> and <xref linkend="include-HTML-file-and-links-in-module-iframe"> for other techniques to incorporate HTML content in <application>PHP-Nuke</application>.</para></listitem></varlistentry></variablelist><para>
<figure id="fig-downloads">
<title>
Administration panel: Downloads.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1066;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1066;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1066;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1066;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Downloads.</phrase>
</textobject>
<caption>
<para>Administration panel: Downloads.</para>
</caption>
</mediaobject>
</figure>
</para><variablelist><varlistentry><term>Downloads:
</term><listitem><para>It creates categories, subcategories and adds files to the download<indexterm><primary>download</primary></indexterm> area. For security reasons, the system does not allow file uploads via HTTP,<indexterm><primary>HTTP</primary></indexterm> only their linking through their HTTP address. If for example the file <emphasis>files.zip<indexterm><primary>zip</primary></indexterm></emphasis> is found in the directory <emphasis>files</emphasis> of our site, we would have to link it as <emphasis>www.oursite.com/files/file.zip<indexterm><primary>zip</primary></indexterm></emphasis>. This allows us to link external resources also. If you have thousands of download links to enter, consult <xref linkend="enter-thousands-of-download-links"> for an automated procedure.<indexterm><primary>procedure</primary></indexterm> Further, in <xref linkend="modifying-PHP-Nuke-downloads-module"> we show how to modify the <application>PHP-Nuke</application> Downloads module.<indexterm><primary>module</primary></indexterm></para></listitem></varlistentry></variablelist><para>
<figure id="fig-edit-admins">
<title>
Administration panel: Edit Admins.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1067;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1067;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1067;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1067;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Edit Admins.</phrase>
</textobject>
<caption>
<para>Administration panel: Edit Admins.</para>
</caption>
</mediaobject>
</figure>
</para><variablelist><varlistentry><term>Edit<indexterm><primary>Edit</primary></indexterm>&nbsp;Admins:
</term><listitem><para>Enables us to add new administrators, defining their access levels. Besides having a super administrator it is in fact possible to activate<indexterm><primary>activate</primary></indexterm> only partial functions for the various administrators. For example, for an editorial activity, you can create sub-administrators<indexterm><primary>sub-administrators</primary></indexterm> and enable only the News administration functions for them.</para></listitem></varlistentry></variablelist><para>
<figure id="fig-edit-users">
<title>
Administration panel: Edit Users.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1068;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1068;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1068;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1068;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Edit Users.</phrase>
</textobject>
<caption>
<para>Administration panel: Edit Users.</para>
</caption>
</mediaobject>
</figure>
</para><variablelist><varlistentry><term>Edit<indexterm><primary>Edit</primary></indexterm>&nbsp;Users:
</term><listitem><para>From here it is possible to manually add new users and to modify existing ones, choosing their profile by typing the nickname in the appropriate form. Through the same form it is also possible to delete a user, by simply changing the drop-down menu selection from &ldquo;modify&rdquo; to &ldquo;delete&rdquo;.</para></listitem></varlistentry></variablelist><para>
<figure id="fig-encyclopedia">
<title>
Administration panel: Encyclopedia.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1069;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1069;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1069;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1069;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Encyclopedia.</phrase>
</textobject>
<caption>
<para>Administration panel: Encyclopedia.</para>
</caption>
</mediaobject>
</figure>
</para><variablelist><varlistentry><term>Encyclopedia<indexterm><primary>Encyclopedia</primary></indexterm>:
</term><listitem><para>Allows the creation of multiple word lists (choosing also the language), after having created an encyclopedia we can proceed to the insertion of terms.<indexterm><primary>terms</primary></indexterm></para><caution>
<title> Attention!</title>
<para>
You can only insert terms in an encyclopedia after you have already entered the encyclopedia's title!
</para>
</caution>
<para>The whole interface is contained in one single screen,<indexterm><primary>screen</primary></indexterm> so that for entering the encyclopedia terms you will have to scroll down, then insert the term, its description and also choose the encyclopedia you want to have it in. If you have thousands of terms,<indexterm><primary>terms</primary></indexterm> such an approach is not practical. You may want to have a look at the techniques presented in <xref linkend="enter-thousands-of-web-links"> (for web links) and <xref linkend="enter-thousands-of-download-links"> (for download links) and adapt them to the Encyclopedia module.<indexterm><primary>module</primary></indexterm></para><para>For internationalization (i18n) issues regarding the Encyclopedia module,<indexterm><primary>module</primary></indexterm> see <xref linkend="make-encyclopedia-international">. You can also use the Random Quotes block (<xref linkend="PHP-Nuke-Random-Quotes-block">) to create a random encyclopedia.<indexterm><primary>encyclopedia</primary></indexterm></para></listitem></varlistentry></variablelist><para>
<figure id="fig-ephemerids">
<title>
Administration panel: Ephemerids.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1070;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1070;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1070;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1070;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Ephemerids.</phrase>
</textobject>
<caption>
<para>Administration panel: Ephemerids.</para>
</caption>
</mediaobject>
</figure>
</para><variablelist><varlistentry><term>Ephemerids:<indexterm><primary>Ephemerids</primary></indexterm>
</term><listitem><para>Allows the insertion of recurrent events choosing the date and inserting a description. Given such an event in the Ephemerids table, the Ephemerids block will display its description on the day that it occured. More than one events on a given day are possible, of course. To modify such an event,<indexterm><primary>event</primary></indexterm> you have to scroll up to the bottom of the screen, choose the desired date and then proceed as usual. For a more speedy alternative, see <xref linkend="enter-thousands-of-ephemerids">.</para></listitem></varlistentry></variablelist><para>
<figure id="fig-faq">
<title>
Administration panel: FAQ.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1071;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1071;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1071;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1071;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: FAQ.</phrase>
</textobject>
<caption>
<para>Administration panel: FAQ.</para>
</caption>
</mediaobject>
</figure>
</para><variablelist><varlistentry><term>FAQ<indexterm><primary>FAQ</primary></indexterm>:
</term><listitem><para>Allows the creation of the main FAQ categories and all related questions/answers. After a category has been entered, you must click on its content to be able to enter, delete or modify a FAQ.<indexterm><primary>FAQ</primary></indexterm></para><para>If you want to display HTML code in a FAQ,<indexterm><primary>FAQ</primary></indexterm> have a look at <xref linkend="display-html-code-in-faq">. See also <xref linkend="duplicating-PHP-Nuke-FAQ-module"> if you want to duplicate the FAQ module.<indexterm><primary>module</primary></indexterm></para></listitem></varlistentry></variablelist><para>
<figure id="fig-forum">
<title>
Administration panel: Forums.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1072;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1072;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1072;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1072;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Forums.</phrase>
</textobject>
<caption>
<para>Administration panel: Forums.</para>
</caption>
</mediaobject>
</figure>
</para><variablelist><varlistentry><term>Splatt&nbsp;Forum<indexterm><primary>Forum</primary></indexterm>:
</term><listitem><para>The management of the forum is divided in 4 areas<footnote><para>This applies to <application>PHP-Nuke</application> version 6.0, that has the Splatt Forum installed, or to those installations of a later version that nevertheless use the Splatt Forum module. For the administration functions of the phpBB Forum, see <xref linkend="phpBB-Forum-administration">.</para></footnote>: </para><itemizedlist><listitem><para>Preferences:<indexterm><primary>Preferences</primary></indexterm> It manages the characteristics of the forum (For security reasons it's advisable to deactivate the option to mail in HTML).</para></listitem><listitem><para>Categories and forum:<indexterm><primary>forum</primary></indexterm> defines the categories, the forums included in them, the moderators of every forum,<indexterm><primary>forum</primary></indexterm> levels of access etc... For a forum to be visible, you MUST activate at least one moderator otherwise the forum won't show up!</para></listitem><listitem><para>Ranks:<indexterm><primary>Ranks</primary></indexterm> defines the attention thresholds for the forum. Upon reception of the nth post, aproppriate images will be attached to attract proper attention of the visitors.</para></listitem><listitem><para>Users: moderator management through a complete list of the registered users.</para></listitem></itemizedlist></listitem></varlistentry></variablelist><para>
<figure id="fig-referers">
<title>
Administration panel: HTTP Referers.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1073;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1073;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1073;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1073;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: HTTP Referers.</phrase>
</textobject>
<caption>
<para>Administration panel: HTTP Referers.</para>
</caption>
</mediaobject>
</figure>
</para><variablelist><varlistentry><term>HTTP&nbsp;Referers<indexterm><primary>Referers</primary></indexterm>:
</term><listitem><para>It displays the URL of the site the visitor was on, before coming to our site. See also the IP Tracking module in <xref linkend="PHP-Nuke-IP-Tracking-module"> and the Protector module in <xref linkend="PHP-Nuke-Protector-module"> for a similar, but extended, functionality.<indexterm><primary>functionality</primary></indexterm></para></listitem></varlistentry></variablelist><para>
<figure id="fig-messages">
<title>
Administration panel: Messages.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1074;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1074;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1074;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1074;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Messages.</phrase>
</textobject>
<caption>
<para>Administration panel: Messages.</para>
</caption>
</mediaobject>
</figure>
</para><variablelist><varlistentry><term>Messages<indexterm><primary>Messages</primary></indexterm>:
</term><listitem><para>It creates a central block in the Home Page in order to send selective messages to the users. The messages can be sent to only registered users, to non-registered users, to the administrator or one may carry out a selection by language. They also may carry a expiration date,<indexterm><primary>date</primary></indexterm> making it possible to say, for example, &ldquo;show this message for 1, 2, 5, 15, 30 days, or for unlimited time&rdquo;.</para></listitem></varlistentry></variablelist><para>
<figure id="fig-modules">
<title>
Administration panel: Modules.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1075;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1075;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1075;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1075;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Modules.</phrase>
</textobject>
<caption>
<para>Administration panel: Modules.</para>
</caption>
</mediaobject>
</figure>
</para><variablelist><varlistentry><term>Modules<indexterm><primary>Modules</primary></indexterm>:
</term><listitem><para>Allows for the management of the modules installed. The modules can be activated,<indexterm><primary>activated</primary></indexterm> deactivated or be assigned read permissions. A module can be world-readable,<indexterm><primary>world-readable</primary></indexterm> readable only by the registered users, or only the administrator (<xref linkend="fig-modules-admin">). Further, you can define the module that will be &ldquo;put in Home&rdquo;, i.e. appear in the index.<indexterm><primary>index</primary></indexterm>php page (the &ldquo;Homepage&rdquo; of PHP-Nuke), but see <xref linkend="change-Home-module"> if this seems to be not working.</para><para>
<figure id="fig-modules-admin">
<title>
Modules administration panel.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1076;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1076;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1076;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1076;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Modules administration panel.</phrase>
</textobject>
<caption>
<para>Modules administration panel.</para>
</caption>
</mediaobject>
</figure>
</para></listitem></varlistentry></variablelist><para>
<figure id="fig-newsletter">
<title>
Administration panel: Newsletter.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1077;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1077;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1077;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1077;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Newsletter.</phrase>
</textobject>
<caption>
<para>Administration panel: Newsletter.</para>
</caption>
</mediaobject>
</figure>
</para><variablelist><varlistentry><term>Newsletter:
</term><listitem><para>the <application>PHP-Nuke</application> administrator can send a newsletter to the registered<indexterm><primary>registered</primary></indexterm> users who have consented to receive them or send them to all the registered<indexterm><primary>registered</primary></indexterm> users. Attention to spam!</para><para>See <xref linkend="allow-HTML-newsletter"> if you want to allow HTML in your newsletter.<indexterm><primary>newsletter</primary></indexterm></para></listitem></varlistentry></variablelist><para>
<figure id="fig-optimize">
<title>
Administration panel: Optimize DB.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1078;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1078;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1078;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1078;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Optimize DB.</phrase>
</textobject>
<caption>
<para>Administration panel: Optimize DB.</para>
</caption>
</mediaobject>
</figure>
</para><variablelist><varlistentry><term>Optimize&nbsp;DB:
</term><listitem><para>Optimizes the data in the database,<indexterm><primary>base</primary></indexterm> increasing database speed. Use with caution. Backup your database before! See <xref linkend="backup-mysql-using-browser"> for automated backups through the browser - and <xref linkend="restore-PHP-Nuke-from-backup"> in case something goes wrong and you have to restore your database from a backup.<indexterm><primary>backup</primary></indexterm></para></listitem></varlistentry></variablelist><para>
<figure id="fig-preferences">
<title>
Administration panel: Preferences.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1079;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1079;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1079;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1079;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Preferences.</phrase>
</textobject>
<caption>
<para>Administration panel: Preferences.</para>
</caption>
</mediaobject>
</figure>
</para><variablelist><varlistentry><term>Preferences:<indexterm><primary>Preferences</primary></indexterm>
</term><listitem><para>This subject will be treated in <xref linkend="preferences">.</para></listitem></varlistentry></variablelist><para>
<figure id="fig-reviews">
<title>
Administration panel: Reviews.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1080;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1080;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1080;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1080;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Reviews.</phrase>
</textobject>
<caption>
<para>Administration panel: Reviews.</para>
</caption>
</mediaobject>
</figure>
</para><variablelist><varlistentry><term>Reviews<indexterm><primary>views</primary></indexterm>:
</term><listitem><para>It allows us to insert book reviews.<indexterm><primary>reviews</primary></indexterm> In every book review it is possible to cast a vote,<indexterm><primary>vote</primary></indexterm> a link relative to the subject and finally an image that represents the content. To insert an image, you must save it in the images/reviews folder, then enter its filename (without the path, e.g. pippo.png) in the aproppriate field.</para><para>Further, you can set up a title and a description for the reviews main page.</para><para>We discuss how to modify the Reviews module in <xref linkend="modifying-php-nuke-module-reviews">.</para></listitem></varlistentry></variablelist><para>
<figure id="fig-sections">
<title>
Administration panel: Sections.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1081;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1081;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1081;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1081;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Sections.</phrase>
</textobject>
<caption>
<para>Administration panel: Sections.</para>
</caption>
</mediaobject>
</figure>
</para><variablelist><varlistentry><term>Sections:<indexterm><primary>Sections</primary></indexterm>
</term><listitem><para>here you can manage the sections and their contents. It is possible to associate an image to the section subject,<indexterm><primary>subject</primary></indexterm> just as it is in the topics.<indexterm><primary>topics</primary></indexterm> It is possible to add articles to the sections selecting the aproppriate category through a radio button, to divide long texts using the &lt;! -- pagebreak -- &gt; tag and to edit or cancel already added sections.</para></listitem></varlistentry></variablelist><para>
<figure id="fig-submissions">
<title>
Administration panel: Submissions.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1082;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1082;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1082;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1082;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Submissions.</phrase>
</textobject>
<caption>
<para>Administration panel: Submissions.</para>
</caption>
</mediaobject>
</figure>
</para><variablelist><varlistentry><term>Submissions:<indexterm><primary>Submissions</primary></indexterm>
</term><listitem><para>Here you can manage articles inserted by others. It is the moderation area of the News module that we have already analyzed in this section. You can publish, modify or delete submitted articles - there is even a field for &ldquo;notes<indexterm><primary>notes</primary></indexterm>&rdquo; that allows the webmaster to enter a comment to the article that will be visually distinguished from the main text by a cursive font.</para></listitem></varlistentry></variablelist><para>
<figure id="fig-surveys">
<title>
Administration panel: Surveys.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1083;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1083;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1083;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1083;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Surveys.</phrase>
</textobject>
<caption>
<para>Administration panel: Surveys.</para>
</caption>
</mediaobject>
</figure>
</para><variablelist><varlistentry><term>Surveys/Polls:<indexterm><primary>Polls</primary></indexterm>
</term><listitem><para>Creates a new survey for the site, edits or cancels old ones. It is possible to insert up to 10 different answers to every survey.<indexterm><primary>survey</primary></indexterm> In the context of the creation of the survey it is possible, on the same page, to publish a news article that announces its creation.</para></listitem></varlistentry></variablelist><para>
<figure id="fig-topics">
<title>
Administration panel: Topics.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1084;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1084;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1084;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1084;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Topics.</phrase>
</textobject>
<caption>
<para>Administration panel: Topics.</para>
</caption>
</mediaobject>
</figure>
</para><variablelist><varlistentry><term>Topics:
</term><listitem><para>Allows you to create new topics and the association, through a pop-up<indexterm><primary>pop-up</primary></indexterm> menu,<indexterm><primary>menu</primary></indexterm> of corresponding images (<xref linkend="fig-add-topic">). The images must have been copied to the images/topics folder previously.</para><para>
<figure id="fig-add-topic">
<title>
Administration panel: Add a new topic.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1085;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1085;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1085;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1085;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Add a new topic.</phrase>
</textobject>
<caption>
<para>Administration panel: Add a new topic.</para>
</caption>
</mediaobject>
</figure>
</para></listitem></varlistentry></variablelist><para>
<figure id="fig-weblinks">
<title>
Administration panel: Web Links.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1086;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1086;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1086;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1086;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Web Links.</phrase>
</textobject>
<caption>
<para>Administration panel: Web Links.</para>
</caption>
</mediaobject>
</figure>
</para><variablelist><varlistentry><term>Web&nbsp;Links:
</term><listitem><para>Allows us to edit links published by others, create categories for archiving the links, eliminate links, see user messages informing us of any broken links through an interface very similar to the downloads<indexterm><primary>ads</primary></indexterm> section and add new links. </para><para>If you have many links to enter, an automatic procedure based on scripting,<indexterm><primary>scripting</primary></indexterm> as discussed in <xref linkend="enter-thousands-of-web-links">, may be of interest to you. Further, in <xref linkend="modifying-php-nuke-module-web-links"> we show how to modify the <application>PHP-Nuke</application> Web Links module.<indexterm><primary>module</primary></indexterm></para></listitem></varlistentry></variablelist><para>
<figure id="fig-logout">
<title>
Administration panel: Logout.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1087;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1087;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1087;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1087;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Logout.</phrase>
</textobject>
<caption>
<para>Administration panel: Logout.</para>
</caption>
</mediaobject>
</figure>
</para><variablelist><varlistentry><term>Logout/Exit<indexterm><primary>Exit</primary></indexterm>:
</term><listitem><para>Exits from the administration area rendering the cookie invalid. It is good practice to login logout after having finished working with <application>PHP-Nuke</application>. For security reasons (see <xref linkend="cookies">).</para></listitem></varlistentry></variablelist><sect2 id="phpBB-Forum-administration"><title>phpBB Forum administration</title><para>
<figure id="fig-forum-2">
<title>
Administration panel: Forums.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1088;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1088;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1088;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1088;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Forums.</phrase>
</textobject>
<caption>
<para>Administration panel: Forums.</para>
</caption>
</mediaobject>
</figure>
</para><para>Given the length of the administration interface of the phpBB Forum,<indexterm><primary>Forum</primary></indexterm> we will traverse its functions following the order of the menu in the left frame.<indexterm><primary>frame</primary></indexterm></para><variablelist><varlistentry><term>Admin&nbsp;Index:<indexterm><primary>Index</primary></indexterm>
</term><listitem><para>Leads back to the administration panel of <application>PHP-Nuke</application> (<xref linkend="administration-functions">).</para></listitem></varlistentry><varlistentry><term>Forum&nbsp;Index:<indexterm><primary>Index</primary></indexterm>
</term><listitem><para>Leads back to the main Forum page.</para></listitem></varlistentry><varlistentry><term>Preview&nbsp;Forum:<indexterm><primary>Forum</primary></indexterm>
</term><listitem><para>Offers a preview of the forum, keeping the left frame with the administration functions in place.</para></listitem></varlistentry><varlistentry><term>Management:
</term><listitem><para>Here you can create the categories that will form the criteria<indexterm><primary>criteria</primary></indexterm> for grouping the forums, old and new ones. It is also possible to change their order inside a category, lock and unlock<indexterm><primary>lock</primary></indexterm> a forum, and configure the pruning function for every forum.<indexterm><primary>forum</primary></indexterm> Pruning is the self-cleaning action that deletes all threads that did not receive a posting in the last N days, N being individually set by the administrator.</para></listitem></varlistentry><varlistentry><term>Pruning:<indexterm><primary>Pruning</primary></indexterm>
</term><listitem><para>Another way to reach the pruning function (instead of the Management link above).</para></listitem></varlistentry><varlistentry><term>Avatar&nbsp;management:<indexterm><primary>management</primary></indexterm>
</term><listitem><para>Deletes unwanted avatars.</para></listitem></varlistentry><varlistentry><term>Backup&nbsp;database:<indexterm><primary>base</primary></indexterm>
</term><listitem><para>Makes a backup copy of the database. Since <application>PHP-Nuke</application> also posesses the same function,<indexterm><primary>function</primary></indexterm> it is recommended to use that one from PHP-Nuke's administration panel (<xref linkend="administration-functions">). For a do-it-yourself solution, see <xref linkend="backup-mysql-using-browser">, but bear in mind that all these methods will fail, if your database has become so large that <acronym>PHP</acronym> is exhausting its <acronym>CPU</acronym> time limit and breaks execution. In such a case, only the MySQL mysqldump command-line utility can backup<indexterm><primary>backup</primary></indexterm> your DB.</para></listitem></varlistentry><varlistentry><term>Configuration:
</term><listitem><para>This is the forum configuration panel.<indexterm><primary>panel</primary></indexterm> From all the functions present, we would like to bring the following ones to your attention:</para><itemizedlist><listitem><para>Flood interval: Minimum number of seconds that must pass between a post and the next one (by the same person).</para></listitem><listitem><para>Topics per page: Number of threads per page.</para></listitem><listitem><para>Posts per page: Number of posts per page.</para></listitem><listitem><para>Posts for popular threshold:<indexterm><primary>threshold</primary></indexterm> Number of posts required to render a thread as &ldquo;popular&rdquo;.</para></listitem><listitem><para>Allowed HTML tags: The HTML tags that the users are allowed to use in their text (e.g. links, tables etc.). See <xref linkend="allow-special-HTML-tags"> for the same subject regarding <application>PHP-Nuke</application> in general.</para></listitem><listitem><para>Allow username changes: Enables changing one's nickname (don't set this to &ldquo;yes&rdquo;).</para></listitem><listitem><para>Enable remote avatars:<indexterm><primary>avatars</primary></indexterm> Enables linking one's avatar to an image from a remote site (e.g. one's photo).</para></listitem><listitem><para>E-mail settings:<indexterm><primary>settings</primary></indexterm> management of e-mail operations (be it mailing actions or mail notifications).</para></listitem></itemizedlist></listitem></varlistentry><varlistentry><term>Mass&nbsp;e-mails:
</term><listitem><para>Allows for mass e-mailing of users or groups through a newsletter.<indexterm><primary>newsletter</primary></indexterm> <application>PHP-Nuke</application> posseses this functionality too.</para></listitem></varlistentry><varlistentry><term>Restore&nbsp;database:<indexterm><primary>base</primary></indexterm>
</term><listitem><para>Reloads a backup file of the database (don't play too much with this).</para></listitem></varlistentry><varlistentry><term>Smilies:
</term><listitem><para>Allows a personalization of the character sequences that will be mapped to smiley icons.<indexterm><primary>icons</primary></indexterm></para></listitem></varlistentry><varlistentry><term>Word&nbsp;censor:<indexterm><primary>censor</primary></indexterm>
</term><listitem><para>Enables censorship of bad words (the ones you enter in the list). <application>PHP-Nuke</application> posesses a similar bad word list in the config.<indexterm><primary>config</primary></indexterm>php file (<xref linkend="config-php-file">).</para></listitem></varlistentry><varlistentry><term>Group/admin&nbsp;management:<indexterm><primary>management</primary></indexterm>
</term><listitem><para>Here you can create groups, which can be &ldquo;open&rdquo;, &ldquo;closed&rdquo; or &ldquo;hidden&rdquo;. In an open group, anyone can choose to join. A closed group is viewable,<indexterm><primary>viewable</primary></indexterm> but only administrators can add members to them. A hidden groups is only viewable by an administrator.<indexterm><primary>administrator</primary></indexterm></para><tip>
<title>
How to add a user to a group
</title>
<para>
To add members you don't even need to be in the forum's admin section: in any normal forum page click on usergroups, you will see all available groups depending on your access level, if you have admin access you will be able to add/remove/approve users from this page.
</para>
</tip>
</listitem></varlistentry><varlistentry><term>Permissions:
</term><listitem><para>You can assign permissions to a group here.</para></listitem></varlistentry><varlistentry><term>Styles&nbsp;admin:
</term><listitem><para>In the standalone phpBB forum, you can manage the forum themes<indexterm><primary>themes</primary></indexterm> from here. However, this function does not have any effect on PHP-Nuke, whose themes<indexterm><primary>themes</primary></indexterm> are still managed from the administration panel (<xref linkend="administration-functions">). If a theme does not work with the phpBB forum in PHP-Nuke, you should not try to activate it through this function,<indexterm><primary>function</primary></indexterm> it wil still not work. Try to contact the designer instead, and ask for a <application>PHP-Nuke</application> conforming theme.<indexterm><primary>theme</primary></indexterm></para></listitem></varlistentry><varlistentry><term>Ban&nbsp;control:<indexterm><primary>control</primary></indexterm>
</term><listitem><para>Allows you to ban a username, an e-mail address, or an IP address (or a group of IP addresses). See <xref linkend="PHP-Nuke-IP-Tracking-module"> and <xref linkend="PHP-Nuke-Protector-module"> for add-on modules that pursue the same subject.<indexterm><primary>subject</primary></indexterm></para></listitem></varlistentry><varlistentry><term>Disallow&nbsp;name:
</term><listitem><para>You can enter the usernames you wish to make unavailable to users.</para></listitem></varlistentry><varlistentry><term>User&nbsp;admin/management:
</term><listitem><para>Allows the administrator to manage user data.<indexterm><primary>data</primary></indexterm></para></listitem></varlistentry><varlistentry><term>Permissions:
</term><listitem><para>Allows the adminstrator to set user permissions.<indexterm><primary>permissions</primary></indexterm></para></listitem></varlistentry><varlistentry><term>Ranks:<indexterm><primary>Ranks</primary></indexterm>
</term><listitem><para>You can define user &ldquo;categories&rdquo; here, the so-called ranks. A user will attain a certain rank,<indexterm><primary>rank</primary></indexterm> after having posted a threshold number X of forum posts - the rank name, icon and threshold being freely configurable.</para></listitem></varlistentry></variablelist></sect2>
</sect1>
<sect1 id="preferences"><title>The Preferences Page </title><para>
<figure id="fig-preferences-2">
<title>
Administration panel: Preferences.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1089;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1089;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1089;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1089;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Preferences.</phrase>
</textobject>
<caption>
<para>Administration panel: Preferences.</para>
</caption>
</mediaobject>
</figure>
</para><para>Here are the parameters needed for the configuration of the config.<indexterm><primary>config</primary></indexterm>php file (<xref linkend="config-php-file">) through the admin/preferences area:</para><itemizedlist><listitem><para>General Site Info (<xref linkend="fig-general-site-info">):</para><itemizedlist><listitem><para>Site name: It corresponds to the <ulink url="http://www.w3.org/TR/html4/struct/global.html#adef-title">title</ulink> tag, it is what appears up in the right bar of the browser. It is very important for the <ulink url="http://www.w3.org/TR/html4/appendix/notes.html#h-B.4">search engines</ulink>.</para></listitem><listitem><para>Site URL:<indexterm><primary>URL</primary></indexterm> It is the internet address of your site.</para></listitem><listitem><para>Logo:<indexterm><primary>Logo</primary></indexterm> It is the logo of your site. In standard themes and themes not modified much it is the Logo that appears up on the left.</para></listitem><listitem><para>Slogan:<indexterm><primary>Slogan</primary></indexterm> It is equivalent to the <ulink url="http://www.w3.org/TR/html4/struct/global.html#edef-META">description</ulink> tag, it's also very important for the <ulink url="http://www.w3.org/TR/html4/appendix/notes.html#h-B.4">search engines</ulink>.</para></listitem><listitem><para>Beginning date of the site: It's the date that appears in the statistics<indexterm><primary>statistics</primary></indexterm> module.<indexterm><primary>module</primary></indexterm></para></listitem><listitem><para>Administrator e-mail : it is the e-mail which will receive the notifications<indexterm><primary>notifications</primary></indexterm> for article insertions by third parties and the mails from the &ldquo;contact us&rdquo; module.<indexterm><primary>module</primary></indexterm></para></listitem><listitem><para>Articles in Top Page: Specifies the number of news articles that can be displayed in the main page of the news module.<indexterm><primary>module</primary></indexterm></para></listitem><listitem><para>Articles in Home: Specifies the number of news articles that can be displayed in the home page of the site (if the news module is the main one).</para></listitem><listitem><para>Stories in old articles box: Specifies the number of news articles that can be displayed in the old articles box. Note, however, that articles never get moved anywhere. An archived article,<indexterm><primary>article</primary></indexterm> is any article except for the first 10 articles (or whatever number you have in Preferences for &quot;number of stories in Home&quot;). The Old Articles block starts with the 11th newest article,<indexterm><primary>article</primary></indexterm> and goes back from there (again, it depends on &quot;stories in Home&quot;).</para></listitem><listitem><para>Activate ultramode:<indexterm><primary>ultramode</primary></indexterm> specifies if other sites can take news titles from our site.</para></listitem><listitem><para>Allow anonymous to post : Specifies whether anonymous users can write comments.<indexterm><primary>comments</primary></indexterm></para></listitem><listitem><para>Default theme:<indexterm><primary>theme</primary></indexterm> defines the default theme of the site.</para></listitem><listitem><para>Select language: defines the default language of the site.</para></listitem><listitem><para>local time format:<indexterm><primary>format</primary></indexterm> defines the format of the local time (depends on the server,<indexterm><primary>server</primary></indexterm> if it is running linux, this is controlled in <emphasis><ulink url="http://www.debian.org/doc/manuals/intro-i18n/ch-locale.en.html">/usr/share/locale</ulink></emphasis>). See also <xref linkend="date-time">.</para></listitem></itemizedlist><para>
<figure id="fig-general-site-info">
<title>
General site info in the Preferences page.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1090;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1090;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1090;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1090;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>General site info in the Preferences page.</phrase>
</textobject>
<caption>
<para>General site info in the Preferences page.</para>
</caption>
</mediaobject>
</figure>
</para></listitem><listitem><para>Multilingual options:</para><itemizedlist><listitem><para>activate the multilanguage characteristics:<indexterm><primary>characteristics</primary></indexterm> choose whether the site should support a multilingual functionality or not</para></listitem><listitem><para>display the small flags in place of the list: if the multilingual option is activated then this decides whether the block should display the small state flags in place of a list of language names (see <xref linkend="fig-languages">).</para></listitem></itemizedlist></listitem><listitem><para>Banners options:</para><itemizedlist><listitem><para>activate banners : sets up the option to use banner rotation on the site. The banners will be positioned in the header.<indexterm><primary>header</primary></indexterm> See <xref linkend="PHP-Nuke-header-change-banner-placement"> on how to change the banner's position in the header.<indexterm><primary>header</primary></indexterm> If you are interested in other ways of ad placement in PHP-Nuke, see <xref linkend="advertisements-in-php-nuke-blocks"> on how to display ad banners in <application>PHP-Nuke</application> blocks and <xref linkend="advertisements-in-php-nuke-modules"> on how to display advertisements in <application>PHP-Nuke</application> modules.<indexterm><primary>modules</primary></indexterm></para></listitem></itemizedlist></listitem><listitem><para>Footer messages:</para><itemizedlist><listitem><para>For the footer of the page, imagine we have to insert 3 texts in a table that is 100% wide and positioned centrally:</para><itemizedlist><listitem><para>Page Footer Line 1: first text to insert<indexterm><primary>insert</primary></indexterm></para></listitem><listitem><para>Page Footer Line 2: second text to insert<indexterm><primary>insert</primary></indexterm></para></listitem><listitem><para>Page Footer Line 3: third text to insert<indexterm><primary>insert</primary></indexterm></para></listitem></itemizedlist><para>Example: Suppose you have some &quot;powered by&quot; icons in the images/powered directory, like powered_by_linux.png, powered_by_apache.png,<indexterm><primary>powered_by_apache.png</primary></indexterm> powered_by_mysql.png etc. Then you can insert the following HTML code in one of the above footer<indexterm><primary>footer</primary></indexterm> lines and the icons will appear in the aproppriate footer line (<xref linkend="fig-footer">):</para><screen><![CDATA[<p align=center>
]]><![CDATA[<a href='http://www.linux.org' target='blank'>
]]><![CDATA[<img src='images/powered/powered_by_linux.png' border='0'
]]><![CDATA[Alt='Linux Operating System' hspace='10'></a>
]]><![CDATA[<a href='http://www.apache.org' target='blank'>
]]><![CDATA[<img src='images/powered/powered_by_apache.png' border='0'
]]><![CDATA[Alt='Apache Web Server' hspace='10'></a>
]]><![CDATA[<a href='http://www.mysql.org' target='blank'>
]]><![CDATA[<img src='images/powered/powered_by_mysql.png' border='0'
]]><![CDATA[Alt='mySQL Database' hspace='10'></a>
]]><![CDATA[<a href='http://www.php.net' target='blank'>
]]><![CDATA[<img src='images/powered/powered_by_php.png' border='0'
]]><![CDATA[Alt='PHP Homepage Preprocessor' hspace='10'></a>
]]><![CDATA[<a href='http://phpnuke.org' target='blank'>
]]><![CDATA[<img src='images/powered/powered_by_nuke.png' border='0'
]]><![CDATA[Alt='PHP-Nuke Content Management System' hspace='10'></a>
]]><![CDATA[</p>
]]></screen><para>
<figure id="fig-footer">
<title>
Icons in the footer.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1091;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1091;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1091;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1091;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Icons in the footer.</phrase>
</textobject>
<caption>
<para>Icons in the footer.</para>
</caption>
</mediaobject>
</figure>
</para></listitem></itemizedlist></listitem><listitem><para>Backend configuration:<indexterm><primary>configuration</primary></indexterm></para><itemizedlist><listitem><para>Backend title:<indexterm><primary>title</primary></indexterm> The title that will appear in the file from which other sites get our newsfeed.<indexterm><primary>newsfeed</primary></indexterm></para></listitem><listitem><para>Backend language: language for the newsfeed file.</para></listitem></itemizedlist></listitem><listitem><para>Mail New Stories to Admin:<indexterm><primary>Admin</primary></indexterm></para><itemizedlist><listitem><para>Notify new submissions by e-mail:<indexterm><primary>e-mail</primary></indexterm> It defines whether the administrator gets an e-mail when a user inserts a news article.<indexterm><primary>article</primary></indexterm></para></listitem><listitem><para>E-mail to send the message: e-mail to which the notification message will be sent.</para></listitem><listitem><para>E-mail subject:<indexterm><primary>subject</primary></indexterm> the text that will be inserted in the subject line of the message (e.g. &ldquo;NEWS for my site&rdquo;)</para></listitem><listitem><para>E-mail message: notification text (e.g. &ldquo;Hey! You got a new submission for your site.&rdquo;).</para></listitem><listitem><para>E-mail account (From): who has sent the message (typically something like &ldquo;Webmaster<indexterm><primary>Webmaster</primary></indexterm>&rdquo;).</para></listitem></itemizedlist></listitem><listitem><para>Comments moderation:<indexterm><primary>moderation</primary></indexterm></para><itemizedlist><listitem><para>Type of Moderation: chooses whether a moderation should be set up for the comments or not. The options available are: </para><itemizedlist><listitem><para>No moderation<indexterm><primary>moderation</primary></indexterm></para></listitem><listitem><para>Moderation by Admin<indexterm><primary>Admin</primary></indexterm></para></listitem><listitem><para>Moderation by Users</para></listitem></itemizedlist></listitem></itemizedlist></listitem><listitem><para>Comments option:</para><itemizedlist><listitem><para>Comment limit in Bytes: sets up the maximum size for the comments.<indexterm><primary>comments</primary></indexterm></para></listitem><listitem><para>Anonymous default name: assigns a name to the persons who chose to remain unregistered.<indexterm><primary>unregistered</primary></indexterm></para></listitem></itemizedlist></listitem><listitem><para>Graphics options:</para><itemizedlist><listitem><para>Graphical administration menu:<indexterm><primary>menu</primary></indexterm> sets up whether to have icons or text in the administration area.</para></listitem></itemizedlist></listitem><listitem><para>Miscelaneous options:</para><itemizedlist><listitem><para>Activate HTTP referers:<indexterm><primary>referers</primary></indexterm> whether statistics regarding the origin of the visits should be gathered.</para></listitem><listitem><para>How many referrers you want as maximum: the maximum number of statistics<indexterm><primary>statistics</primary></indexterm> pertaining to the origin of the visits (max 2000).</para></listitem><listitem><para>Activate comments in polls:<indexterm><primary>polls</primary></indexterm> Whether comments are allowed in the surveys or not.</para></listitem><listitem><para>Activate comments in articles: Whether comments are allowed in the articles or not.</para></listitem></itemizedlist></listitem><listitem><para>Users options:</para><itemizedlist><listitem><para>Minimum users password length: for security reasons it is advisable to set up a rather long password.<indexterm><primary>password</primary></indexterm></para></listitem></itemizedlist></listitem><listitem><para>Censure options:</para><itemizedlist><listitem><para>Here you can choose to censor some words and also set up the criteria for word matching.<indexterm><primary>matching</primary></indexterm> The words to be censored have to be included in the $CensorList array in config.<indexterm><primary>config</primary></indexterm>php (<xref linkend="config-php-file">).</para></listitem></itemizedlist></listitem><listitem><para>WebMail service ptions (<xref linkend="fig-webmail-options">): Here you can</para><itemizedlist><listitem><para>set up a message to appear in the footer of every e-mail sent by any user of the site,</para></listitem><listitem><para>set up the permissions for the e-mail and its attachments.<indexterm><primary>attachments</primary></indexterm> In case you allow attachments,<indexterm><primary>attachments</primary></indexterm> you can specify the directory that will temporarily hold them (however, this is not a good idea from the security<indexterm><primary>security</primary></indexterm> point of view, see <xref linkend="security-measures">),</para></listitem><listitem><para>allow for direct viewing of the attachments' content via web,</para></listitem><listitem><para>specify the directory that will hold the attachments of the received e-mails,</para></listitem><listitem><para>specify the maximum number of e-mail accounts that your users will be allowed to set up with WebMail,<indexterm><primary>WebMail</primary></indexterm></para></listitem><listitem><para>specify the default POP3 server (i.e. server that will be used for querying for <emphasis>incoming</emphasis> e-mails),</para></listitem><listitem><para>specify if the header of the e-mail is going to be visible (recommended).</para></listitem></itemizedlist><para>
<figure id="fig-webmail-options">
<title>
WebMail service options in the Preferences page.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1092;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1092;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1092;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1092;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>WebMail service options in the Preferences page.</phrase>
</textobject>
<caption>
<para>WebMail service options in the Preferences page.</para>
</caption>
</mediaobject>
</figure>
</para></listitem></itemizedlist></sect1>
</chapter>
<chapter id="php-nuke-add-ons"><title>PHP-Nuke add-ons</title><para>We present some interesting add-on themes (<xref linkend="php-nuke-add-on-themes">), blocks (<xref linkend="php-nuke-add-on-blocks">) and modules (<xref linkend="PHP-Nuke-add-on-modules">) for <application>PHP-Nuke</application>.</para><sect1 id="php-nuke-add-on-themes"><title>Add-on themes</title><para>In this section we present some interesting add-on themes for PHP-Nuke:</para><itemizedlist><listitem><para>AutoTheme (<xref linkend="PHP-Nuke-AutoTheme">).</para></listitem></itemizedlist><sect2 id="PHP-Nuke-AutoTheme"><title>AutoTheme</title><para><ulink url="http://spidean.mckenzies.net">AutoTheme</ulink> is an HTML Theme System for PostNuke and <application>PHP-Nuke</application>. The current theme system usually requires you to be somewhat familiar with <acronym>PHP</acronym> and the PostNuke or <application>PHP-Nuke</application> architecture.<indexterm><primary>architecture</primary></indexterm> AutoTheme removes this complexity.<indexterm><primary>complexity</primary></indexterm></para><para>AutoTheme's primary benefit is providing users the ability to create <application>PHP-Nuke</application> themes in HTML using their favorite editor , with no use of <acronym>PHP</acronym>.<indexterm><primary>PHP</primary></indexterm> In addition, AutoTheme provides easy customization of every part of your <application>PHP-Nuke</application> site; including block display, custom templates for the Home Page, User Pages and Admin Pages and individual modules.<indexterm><primary>modules</primary></indexterm> The addition of AutoBlocks provides unlimited locations for your blocks. All AutoTheme settings are easily configured from a graphical administration<indexterm><primary>administration</primary></indexterm> interface that is integrated into <application>PHP-Nuke</application>. </para><para>You can get a better idea of AutoTheme's possibilities, if you compare the <ulink url="theme.html">standard layout of a <application>PHP-Nuke</application> theme</ulink> with the <ulink url="autotheme.html">layout offered by AutoTheme</ulink>.</para><para>See also <ulink url="http://spidean.mckenzies.net/PostWrap+index-page-at1nukedocs.phtml">AutoTheme for PHP-Nuke</ulink>, for more details on AutoTheme and <xref linkend="topic-structure">, for more details on PHP-Nuke's theme structure.<indexterm><primary>structure</primary></indexterm></para></sect2>
</sect1>
<sect1 id="php-nuke-add-on-blocks"><title>Add-on blocks</title><para>In this section we present some interesting add-on blocks for PHP-Nuke: </para><itemizedlist><listitem><para>Moon &amp; Sun (<xref linkend="PHP-Nuke-Moon-Sun-block">), </para></listitem><listitem><para>Meteosat (<xref linkend="PHP-Nuke-Meteosat-block">), </para></listitem><listitem><para>Comic (<xref linkend="PHP-Nuke-comic-block">), </para></listitem><listitem><para>Menu Builder (<xref linkend="PHP-Nuke-Menu-Builder">), </para></listitem><listitem><para>Treemenu (PHP) (<xref linkend="PHP-Nuke-Treemenu-with-PHP">), </para></listitem><listitem><para>Treemenu (JS) (<xref linkend="PHP-Nuke-Treemenu-with-Javascript">), </para></listitem><listitem><para>AdSense (<xref linkend="PHP-Nuke-Google-AdSense-block">),</para></listitem><listitem><para>Random Quotes (<xref linkend="PHP-Nuke-Random-Quotes-block">).</para></listitem></itemizedlist><sect2 id="PHP-Nuke-Moon-Sun-block"><title>Moon &amp; Sun block</title><para>
<figure id="fig-moon-moonsun-sun">
<title>
Moon, Moon &amp; Sun and Sun blocks.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1093;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1093;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1093;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1093;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Moon, Moon &amp; Sun and Sun blocks.</phrase>
</textobject>
<caption>
<para>Moon, Moon &amp; Sun and Sun blocks.</para>
</caption>
</mediaobject>
</figure>
</para><para>The Moon and Sun blocks are very simple blocks: they show the current Moon<indexterm><primary>Moon</primary></indexterm> or Sun image, but technically they contain no dynamic components. The blocks incorporate an image with a fixed URL.<indexterm><primary>URL</primary></indexterm> It is left to the provider of the image (the U.S.<indexterm><primary>U.S.</primary></indexterm> Naval Observatory and the NASA Goddard Space Flight Center) to put whatever image is &ldquo;current&rdquo; into the that fixed URL.<indexterm><primary>URL</primary></indexterm> This simplifies the programming of the blocks substancially.</para><para>The <ulink url="http://www.complex-berlin.de/download.php?op=getit&amp;lid=659">Moon block</ulink> shows the daily Lunar Phase. It also shows the Julian Date, and some Moon info and uses a simple cache<indexterm><primary>cache</primary></indexterm> to wait x minutes before grabbing the image again remotely. Stores image in temp cache folder on your site.</para><para>The <ulink url="http://www.complex-berlin.de/download.php?op=getit&amp;lid=658">Sun block</ulink> grabs an image of the sun that is taken daily,<indexterm><primary>daily</primary></indexterm> and places it on your web page. Nice colored Solar Image, includes Sunrise and Sunset info,<indexterm><primary>info</primary></indexterm> that can be customized. Also caches image on your site, and fetches the new image every x minutes.</para><para>The <ulink url="http://www.karakas-online.de/phpnuke/block-Moon_&amp;_Sun.tar">Moon & Sun block</ulink> combines the two images in a single <application>PHP-Nuke</application> block, but omits the information<indexterm><primary>information</primary></indexterm> and the caching functionality.<indexterm><primary>functionality</primary></indexterm></para><tip>
<title>
Caching
</title>
<para>
Even if your <application>PHP-Nuke</application> block does not come with a caching mechanism (which is especially useful in cases where the block's content does not change on literally every page request), this does not mean you are excluded from reaping its benefits! In <xref linkend="accelerating-php-nuke"> we discuss all the caching options you have in detail. You may want to use one of the standard solutions presented there, rather than implement a slightly different caching mechanism with each and every block you install on your site.
</para>
</tip>
</sect2>
<sect2 id="PHP-Nuke-Meteosat-block"><title>Meteosat block</title><para>
<figure id="fig-meteosat">
<title>
Meteosat block.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1094;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1094;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1094;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1094;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Meteosat block.</phrase>
</textobject>
<caption>
<para>Meteosat block.</para>
</caption>
</mediaobject>
</figure>
</para><para>The <ulink url="http://www.karakas-online.de/phpnuke/block-Meteosat.tar">Meteosat block</ulink> will display the most recent Meteosat images of the World and Europe.<indexterm><primary>Europe</primary></indexterm> It is a good example of a block that contains dynamic images whose filenames vary according to some date schema (see <ulink url="http://www.karakas-online.de/myServices/showfile.php?highlight=meteosat">source code of the Meteosat <application>PHP-Nuke</application> block</ulink><footnote><para>Actually, the source code for the <application>PHP-Nuke</application> block is slightly different, but the algorithm is exactly the same.</para></footnote>):</para><para>The images are taken from </para><itemizedlist><listitem><para><ulink url="http://www.wetter.com/home/img/sat/METEOSAT_vis_c/xl/">http://www.wetter.com/home/img/sat/METEOSAT_vis_c/xl/</ulink></para></listitem><listitem><para><ulink url="http://www.wetter.com/home/img/sat/METEOSAT-FULL_ir_c/xl/">http://www.wetter.com/home/img/sat/METEOSAT-FULL_ir_c/xl/</ulink></para></listitem></itemizedlist><para>and are named YYYYMMDDHHMM.jpg, in GMT,<indexterm><primary>GMT</primary></indexterm> so the script has to compute the year, month, day, hour and minutes in GMT,<indexterm><primary>GMT</primary></indexterm> then round down the minutes to either 00 or 30. Thus, although the date and time variables ($year, $month, $day) are dynamic,<indexterm><primary>dynamic</primary></indexterm> the schema itself is fixed: the filename is always of the form $year$month$day$hour$minutes.jpg.</para><para>Due to delays,<indexterm><primary>delays</primary></indexterm> the script doesn't try to get the exact latest image, it rather subtracts a safety intervall of 3600 sec from the current time, before it starts the calculations.<indexterm><primary>ations</primary></indexterm> This way it makes sure an image will always be there.</para></sect2>
<sect2 id="PHP-Nuke-comic-block"><title>Comic block</title><para>This <ulink url="http://www.karakas-online.de/phpnuke/block-User_Friendly.tar">UserFriendly block</ulink> will display the daily comic from the well-known <ulink url="http://www.userfriendly.org">User Friendly site</ulink>. It reads the <ulink url="http://www.userfriendly.org/static/">User Friendly daily cartoon page</ulink> line by line, searches for the pattern<indexterm><primary>pattern</primary></indexterm></para><screen><![CDATA[whatever<IMG ALT="Latest Strip"whateverSRC="imagefile">whatever,
]]></screen><para>extracts the location of the image file (imagefile) from it and displays it in the block.<indexterm><primary>block</primary></indexterm> The <ulink url="http://www.karakas-online.de/myServices/showfile.php?highlight=userfriendly">PHP code of the User Friendly block </ulink> is a classic example of how you can do this &ldquo;scrapping<indexterm><primary>scrapping</primary></indexterm>&rdquo; in <acronym>PHP</acronym> (-Nuke) and is discussed in <xref linkend="display-images-php-nuke-blocks">.</para><important>
<title>
You must respect copyright law!
</title>
<para>
Some people argue that, by using <acronym>PHP</acronym> to find out the right image filename and then send HTML code that instructs the client's browser to request that image from the original site and display it, you don't copy anything yourself, only the client's browser copies the file in the client's video memory, which would be necessary anyway. Thus, the argument goes, no copyright is infringed, since no copies are made by you.
</para>
<para>
However, even if you don't copy the daily comic directly, you use the original author's work to produce a page that can be seen as a &ldquo;derivative work&rdquo;. Even if you argue that what you do is just the same as what any proxy would do, if it where instructed to strip all other content (like advertisements, for example) from the requested page and serve only the image, it is not sure that the court will follow you in this interpretation.
</para>
<para>
To avoid even the remote possibility of breaking copyright law, you are well advised to ask the authors' permission, before you use any comics blocks on your site. Some may not agree, in which case you should respect their wish, but some may do give you permission, perhaps under some easy to accept conditions. For example, to obtain permission to show the UserFriendly cartoon on his site, Chris wrote the author, Illiad, who kindly agreed under the condition to reproduce the ads that come with it on the original UserFriendly page. This way, everybody's happy!
<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_smile.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_smile.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_smile.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_smile.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject>
</para>
</important>
<note>
<title>
Leges sine moribus vanae<footnote><para>Laws without morals are empty.</para></footnote>
</title>
<para>
Actually, we shouldn't have to resort to legal arguments for this - moral alone should suffice to convince you. Please take a moment to think about it.
</para>
</note>
<para>See <xref linkend="PHP-Nuke-Daily-Comic-module"> for a module which displays more than one daily comics.<indexterm><primary>comics</primary></indexterm></para></sect2>
<sect2 id="PHP-Nuke-Menu-Builder"><title>Menu Builder</title><para>
<figure id="fig-my-menu">
<title>
Menu block with Menu Builder.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1095;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1095;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1095;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1095;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Menu block with Menu Builder.</phrase>
</textobject>
<caption>
<para>Menu block with Menu Builder.</para>
</caption>
</mediaobject>
</figure>
</para><para>The <ulink url="http://www.sengers-au.com/Portal/main/modules.php?name=Downloads&amp;d_op=viewdownload&amp;cid=5">Language Menu Builder</ulink> generates a block with a menu on-the-fly from the administration panel.<indexterm><primary>panel</primary></indexterm> You can write the menu in your own language, choose your own images for the menu items and have certain options hidden for 'visitors'. The Menu Builder does not use or change any database items. Thus it wil not become obsolete when tables change in the database (this is true for the Treemenu <xref linkend="PHP-Nuke-Treemenu-with-PHP"> too). See it in action at <ulink url="http://www.sengers-au.com">http://www.sengers-au.com</ulink>, where you will find other interesting downloads around blocks and modules<indexterm><primary>modules</primary></indexterm> too.</para></sect2>
<sect2 id="PHP-Nuke-Treemenu-with-PHP"><title>Treemenu with PHP</title><para>
<figure id="fig-treemenu3-2">
<title>
Treemenu block with <acronym>PHP</acronym>.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1096;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1096;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1096;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1096;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase> Treemenu block with <acronym>PHP</acronym>.</phrase>
</textobject>
<caption>
<para> Treemenu block with <acronym>PHP</acronym>.</para>
</caption>
</mediaobject>
</figure>
</para><para>The <ulink url="http://www.karakas-online.de/phpnuke/block-Treemenu.tgz">Treemenu for PHP-Nuke</ulink> will read a simple, plain text file that contains the &ldquo;nodes&rdquo; and &ldquo;leaves<indexterm><primary>leaves</primary></indexterm>&rdquo; of a menu and will create a block with a Treemenu,<indexterm><primary>menu</primary></indexterm> as shown in <xref linkend="fig-treemenu3-2">. Features include:</para><itemizedlist><listitem><para>No database changes. You only change a text file.</para></listitem><listitem><para>Grouping of menu items (&ldquo;leaves<indexterm><primary>leaves</primary></indexterm>&rdquo; of the Treemenu) under &ldquo;nodes&rdquo;.</para></listitem><listitem><para>Expansion and collapse of the nodes based on the value of an URL parameter.<indexterm><primary>parameter</primary></indexterm> You can thus let a submenu stay &ldquo;open&rdquo; , even after you cliked on a leaf link.</para></listitem><listitem><para>Custom images for nodes (open or closed) and leaves.<indexterm><primary>leaves</primary></indexterm> You can make it look like a window of a file manager.<indexterm><primary>manager</primary></indexterm></para></listitem><listitem><para>More complicated logic possible (e.g. depending on categories etc.), see <ulink url="http://www.karakas-online.de/myTreemenu/refinements.html">Treemenu block for PHPNuke: Refinements</ulink>.</para></listitem></itemizedlist><para>This Treemenu is based on a <acronym>PHP</acronym> class and therefore does not require any client scripting (like Javascript). Thus it will still work on clients with Javascript disabled. On the other side, for every change of the menu,<indexterm><primary>menu</primary></indexterm> like expansion or collapse , a new HTTP page request is made to the server.<indexterm><primary>server</primary></indexterm> Like <acronym>PHP</acronym> itself, the Treemenu is a server-side technology.</para><para>A detailed description of the Treemenu can be found in <ulink url="http://www.karakas-online.de/myTreemenu/">Treemenu block for PHPNuke</ulink>. We also discuss it in <xref linkend="treemenu-block">, in the context of modifying blocks, specifically the Modules block.<indexterm><primary>block</primary></indexterm></para></sect2>
<sect2 id="PHP-Nuke-Treemenu-with-Javascript"><title>Treemenu with Javascript</title><para>
<figure id="fig-treemenu-js">
<title>
Treemenu block with Javascript.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1097;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1097;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1097;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1097;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Treemenu block with Javascript.</phrase>
</textobject>
<caption>
<para>Treemenu block with Javascript.</para>
</caption>
</mediaobject>
</figure>
</para><para>If you are looking for a Treemenu based on Javascript,<indexterm><primary>Javascript</primary></indexterm> you can see one in action at <ulink url="http://www.nuketurk.com">Nuke Turk</ulink> and download from the <application>PHP-Nuke</application> downloads section there. Since Javascript is a client-based technology, the menu will be downloaded in whole once and no further page requests will be necessary to display its nodes and leaves.<indexterm><primary>leaves</primary></indexterm> This may result in slower downloads for the first time, but faster response<indexterm><primary>response</primary></indexterm> times from the menu in expansions and collapses. But it will not work for clients with Javascript disabled.</para><para>An alternative Menu Block is &ldquo;Sommaire Param<61>trable<indexterm><primary>Param<61>trable</primary></indexterm>&rdquo; <footnote><para>This is the original name.</para></footnote>(see also <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=390">Neue Bloecke</ulink>). You can download it from <ulink url="http://www.nukecops.com/downloads-cat-2.html">Customize Menu</ulink>. This add-on allows the admin to set up his own menu for Nuke web sites (replaces the Modules block that lists all the active &amp; visible modules). </para><para>
<figure id="fig-sommaire-parametrable">
<title>
Modules block. created with Sommaire Param<61>trable.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1098;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1098;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1098;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1098;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Modules block. created with Sommaire Param<61>trable.</phrase>
</textobject>
<caption>
<para>Modules block. created with Sommaire Param<61>trable.</para>
</caption>
</mediaobject>
</figure>
</para><para>Features of version 2.0 :</para><itemizedlist><listitem><para>Modules are grouped into categories (sub-menu).</para></listitem><listitem><para>You can choose the display order of each module and category.<indexterm><primary>category</primary></indexterm></para></listitem><listitem><para>You can set up a background color for each category.<indexterm><primary>category</primary></indexterm></para></listitem><listitem><para>You can now add external links in your menu ! (You were restricted to modules<indexterm><primary>modules</primary></indexterm> only in v.1.0).</para></listitem><listitem><para>Multilingual support.</para></listitem><listitem><para>Categories' names can be centered.</para></listitem><listitem><para>You can display a FLASH file instead of the category's name.</para></listitem><listitem><para>You can set images for each module/link.</para></listitem><listitem><para>You can separate categories with horizontal bars.<indexterm><primary>bars</primary></indexterm></para></listitem><listitem><para>You can hide to visitors the modules for members only.</para></listitem><listitem><para>You can choose the class (stylesheet css) for the categories' names.</para></listitem><listitem><para>A 'new mail' icon appears before &quot;Private Messages&quot; if the member has unread Private Messages.<indexterm><primary>Messages</primary></indexterm></para></listitem><listitem><para>The administration console has been improved and is now completely part of the nuke administration panel.<indexterm><primary>panel</primary></indexterm> (2 languages included : French and English)</para></listitem></itemizedlist><para>However, it seems that it does not allow subcategories (FIXME:<indexterm><primary>FIXME</primary></indexterm> Is this correct?). The name of the file to download is sommaire_parametrable_v2.zip.<indexterm><primary>zip</primary></indexterm></para></sect2>
<sect2 id="PHP-Nuke-Google-AdSense-block"><title>Google AdSense block</title><para>If you would like to add Google AdSense ads to your <application>PHP-Nuke</application> based portal<indexterm><primary>portal</primary></indexterm> with ease and customization,<indexterm><primary>customization</primary></indexterm> then this block is for you! Features of v.1.0:</para><itemizedlist><listitem><para>Choice of showing 1 to 4 ads (no huge skyscrapers unless you want them!)</para></listitem><listitem><para>Full color customizations<indexterm><primary>ations</primary></indexterm></para></listitem></itemizedlist><para>To see it in action and to download (registration not required), visit the <ulink url="http://designs.vie4life.com/modules.php?name=Downloads&amp;d_op=viewdownload&amp;cid=9">Downloads section of VieDesigns</ulink>. If you want to do it yourself, or just acquire the knowhow behind advertisements in PHP-Nuke, read <xref linkend="advertisements-in-php-nuke-modules">.</para></sect2>
<sect2 id="PHP-Nuke-Random-Quotes-block"><title>Random Quotes block</title><para>The <ulink url="http://www.skrodahl.net/modules.php?name=Downloads&amp;d_op=viewdownload&amp;cid=4">Random Quotes block</ulink> is an unintrusive block for <application>PHP-Nuke</application> 6.0 that takes its quotes from a &quot;fortune&quot; file of your choice (&quot;fortune&quot; is a humourous quotes program commonly available on most UNIX/Linux/BSD distributions). It snaps easily in place and does not break your layout.<indexterm><primary>layout</primary></indexterm></para><para>
<figure id="fig-Random-Quotes">
<title>
Random Quotes block.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1099;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1099;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1099;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1099;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Random Quotes block.</phrase>
</textobject>
<caption>
<para>Random Quotes block.</para>
</caption>
</mediaobject>
</figure>
</para><para>It is easy to construct a fortune file with the content of your choice, then let block-Random_Quotes display it. The file type is just like the one for 'fortunes': enter quotes in plain text, separated by a per cent sign (%), see the fortunes file that comes with the block.<indexterm><primary>block</primary></indexterm> There also various ready-to-use fortune files available on the Net. </para><para>There is no restriction on the file's content, so it does not have to be humourous - it could just as well be religious, political, philosophical, or just plain marketese.<indexterm><primary>marketese</primary></indexterm> You could for example use it to display random Encyclopedia terms,<indexterm><primary>terms</primary></indexterm> see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=18315">Random Encyclopedia</ulink>.</para></sect2>
</sect1>
<sect1 id="PHP-Nuke-add-on-modules"><title>Add-on modules</title><para>In this section we present some interesting add-on modules for PHP-Nuke: </para><itemizedlist><listitem><para>Daily Comic (<xref linkend="PHP-Nuke-Daily-Comic-module">), </para></listitem><listitem><para>Event Calendar (<xref linkend="PHP-Nuke-event-calendar-module">), </para></listitem><listitem><para>Your Account Tweak (<xref linkend="NSN-Your-Account-Tweak-module">), </para></listitem><listitem><para>Approve Membership (<xref linkend="PHP-Nuke-Approve-Membership-module">), </para></listitem><listitem><para>Gallery (<xref linkend="PHP-Nuke-Gallery-module">), </para></listitem><listitem><para>IP Tracking (<xref linkend="PHP-Nuke-IP-Tracking-module">), </para></listitem><listitem><para>Protector (<xref linkend="PHP-Nuke-Protector-module">), </para></listitem><listitem><para>Web Cam (<xref linkend="PHP-Nuke-WebCam-module">), </para></listitem><listitem><para>My Headlines (<xref linkend="PHP-Nuke-My-Headlines-module">), </para></listitem><listitem><para>PHP-Nuke Tools (<xref linkend="PHP-Nuke-Tools-module">), </para></listitem><listitem><para>Upload (<xref linkend="PHP-Nuke-Upload-module">), </para></listitem><listitem><para>Upload add-on for phpBB (<xref linkend="Upload-add-on-for-phpBB">), </para></listitem><listitem><para>ODP (<xref linkend="php-nuke-ODP-module">), </para></listitem><listitem><para>eCommerce (<xref linkend="PHP-Nuke-eCommerce-module">), </para></listitem><listitem><para>WorkBoard (<xref linkend="PHP-Nuke-WorkBoard-module">).</para></listitem></itemizedlist><sect2 id="PHP-Nuke-Daily-Comic-module"><title>Daily Comic module</title><para>In contrast to the UserFriendly block (<xref linkend="PHP-Nuke-comic-block">), which shows only one cartoon,<indexterm><primary>cartoon</primary></indexterm> the <ulink url="http://www.coding-network.net/modules.php?name=Downloads&amp;d_op=viewdownloaddetails&amp;lid=17">Daily Comic module</ulink> will show a whole series of different daily comics from various authors. However, instead of getting the images from the original web pages, it requests them from some third party web page. This way, the mechanics of achieving this result remain hidden to you - which is not very good from the educational point of view, even though the result is very pleasing. See it in action in <ulink url="http://www.coding-network.net/modules.php?name=comics">Coding Network: Daily Comic module</ulink>. Please read the admonition on copyright in <xref linkend="PHP-Nuke-comic-block">, before you decide to use this module!</para></sect2>
<sect2 id="PHP-Nuke-event-calendar-module"><title>Event calendar</title><para>Based on version 1.5 by Rob Sutton, the Event Calendar (<xref linkend="fig-eventcal">) found in <ulink url="http://phpnuke.holbrookau.net">http://phpnuke.holbrookau.net</ulink> is much updated and features many improvements and add- ons. For example, the adminstration area features configuration via a graphical interface,<indexterm><primary>interface</primary></indexterm> posting of events can be mode rated and users even have the option of adding comments to any event.<indexterm><primary>event</primary></indexterm></para><para>
<figure id="fig-eventcal">
<title>
Event Calendar
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1100;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1100;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1100;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1100;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Event Calendar</phrase>
</textobject>
<caption>
<para>Event Calendar</para>
</caption>
</mediaobject>
</figure>
</para><para>For the installation,<indexterm><primary>installation</primary></indexterm> it is assumed that the user has some knowledge of MySQL and is comfortable with running simple queries before starting. It is highly recommended that you have phpMyAdmin (see <xref linkend="phpmyadmin2">) installed on your server - it will simplify installation and help with error tracking.<indexterm><primary>tracking</primary></indexterm></para><para>
<figure id="fig-eventcal1">
<title>
Calendar1 Block
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1101;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1101;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1101;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1101;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Calendar1 Block</phrase>
</textobject>
<caption>
<para>Calendar1 Block</para>
</caption>
</mediaobject>
</figure>
</para><para>
<figure id="fig-eventcal2">
<title>
Calendar2 Block
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1102;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1102;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1102;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1102;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Calendar2 Block</phrase>
</textobject>
<caption>
<para>Calendar2 Block</para>
</caption>
</mediaobject>
</figure>
</para><para>Add new Block(s) using one or more of the 5 available calendar block types:</para><itemizedlist><listitem><para>Calendar1 (<xref linkend="fig-eventcal1">) shows only events for that day. </para></listitem><listitem><para>Calendar2 (<xref linkend="fig-eventcal2">) is a month calendar with a daily events list. </para></listitem><listitem><para>Calendar3 (<xref linkend="fig-eventcal3">) scrolls a list of coming events. </para></listitem><listitem><para>Calendar4 (<xref linkend="fig-eventcal4">) is the monthly calendar with links and day/month view selection. </para></listitem><listitem><para>Calendar5 (<xref linkend="fig-eventcal5">) is an enhanced ( next 10 events) version of the scrolling calendar block.<indexterm><primary>block</primary></indexterm></para></listitem></itemizedlist><para>
<figure id="fig-eventcal3">
<title>
Calendar3 Block
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1103;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1103;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1103;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1103;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Calendar3 Block</phrase>
</textobject>
<caption>
<para>Calendar3 Block</para>
</caption>
</mediaobject>
</figure>
<figure id="fig-eventcal4">
<title>
Calendar4 Block
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1104;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1104;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1104;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1104;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Calendar4 Block</phrase>
</textobject>
<caption>
<para>Calendar4 Block</para>
</caption>
</mediaobject>
</figure>
<figure id="fig-eventcal5">
<title>
Calendar5 Block
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1105;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1105;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1105;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1105;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Calendar5 Block</phrase>
</textobject>
<caption>
<para>Calendar5 Block</para>
</caption>
</mediaobject>
</figure>
</para><para>For installation instructions, read the readme.<indexterm><primary>readme</primary></indexterm>txt file that comes in the docs folder of the unzipped eventcal-xxx.zip file.</para></sect2>
<sect2 id="NSN-Your-Account-Tweak-module"><title>NSN Your Account Tweak module</title><para>A module that allows the administrator to apply a fine-grained control over user management is <ulink url="http://www.nukefixes.com/article6.html">NSN Your Account Tweak 650 3.0.2</ulink>. According to the description, it offers the following features (<xref linkend="fig-your-account-tweak">):</para><itemizedlist><listitem><para>Provides for servers without mail support.</para></listitem><listitem><para>Optionally send the admin an email when someone unregisters.</para></listitem><listitem><para>Optionally send the admin an email when someone registers.</para></listitem><listitem><para>Admins can allow user self deletion.</para></listitem><listitem><para>Admins can block user theme changes.</para></listitem><listitem><para>Admins can block user email changes.</para></listitem><listitem><para>Blocks usernames with preset strings in them.</para></listitem><listitem><para>Allows for Required User approval by Admin.<indexterm><primary>Admin</primary></indexterm></para></listitem><listitem><para>Admins can suspend users.</para></listitem><listitem><para>Users can be promoted to Admins by SuperUser ONLY.</para></listitem><listitem><para>Admins can resend Activation Email.</para></listitem><listitem><para>Admins can choose to bypass email activation.<indexterm><primary>activation</primary></indexterm></para></listitem><listitem><para>Admins can now view pending user details.</para></listitem><listitem><para>Admins can now modify pending user details.</para></listitem><listitem><para>Improved NavBar scripting.<indexterm><primary>scripting</primary></indexterm> </para></listitem></itemizedlist><para>
<figure id="fig-your-account-tweak">
<title>
Extra options for user management in the NSN Your Account Tweak module.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1106;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1106;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1106;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1106;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Extra options for user management in the NSN Your Account Tweak module.</phrase>
</textobject>
<caption>
<para>Extra options for user management in the NSN Your Account Tweak module.</para>
</caption>
</mediaobject>
</figure>
</para><caution>
<title>
Download the right NSN Your Account Tweak version!
</title>
<para>
Be careful with the version you download from this module! The number 650, for example, indicates that it is only for <application>PHP-Nuke</application> 6.5. Use only the version that is in accordance with your installed <application>PHP-Nuke</application> version, otherwise you are guaranteed to mess up your installation completely.
</para>
</caution>
</sect2>
<sect2 id="PHP-Nuke-Approve-Membership-module"><title>Approve Membership module</title><para>
<figure id="fig-approve-membership-pending-applications">
<title>
Pending applications in the Approve Membership module.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1107;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1107;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1107;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1107;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Pending applications in the Approve Membership module.</phrase>
</textobject>
<caption>
<para>Pending applications in the Approve Membership module.</para>
</caption>
</mediaobject>
</figure>
</para><para>The <ulink url="http://www.ulsoft.scarbridge.co.uk">Approve Membership module</ulink> allows an administrator to approve membership applications.<indexterm><primary>ations</primary></indexterm> The applicant's details are sent to a pending users table and a notification<indexterm><primary>notification</primary></indexterm> email is sent to the administrator.<indexterm><primary>administrator</primary></indexterm> A list of pending applicants is displayed to the administrator,<indexterm><primary>administrator</primary></indexterm> who can delete or approve as he thinks fit (see <xref linkend="fig-approve-membership-pending-applications">). On approval,<indexterm><primary>approval</primary></indexterm> the normal email is sent to the applicant with the activation link. The following options are available: </para><itemizedlist><listitem><para>Add a customisable message to this email (see <xref linkend="fig-approve-membership-approval-message">).</para></listitem><listitem><para>Send a follow up email to an applicant.<indexterm><primary>applicant</primary></indexterm></para></listitem><listitem><para>Send an email to a rejected applicant.<indexterm><primary>applicant</primary></indexterm></para></listitem><listitem><para>All emails are customizable.<indexterm><primary>customizable</primary></indexterm></para></listitem></itemizedlist><para>
<figure id="fig-approve-membership-approval-message">
<title>
Approval message in the Approve Membership module.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1108;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1108;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1108;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1108;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Approval message in the Approve Membership module.</phrase>
</textobject>
<caption>
<para>Approval message in the Approve Membership module.</para>
</caption>
</mediaobject>
</figure>
</para><para>See also <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=83">Authorize accounts</ulink> for an in-depth discussion. </para><para>The new <ulink url="http://www.karakas-online.de/downloads/Approve_Membership3.0-6.9.zip">version 3.0 of the Approve Membership module for <application>PHP-Nuke</application> 6.9</ulink> offers even more facilities, such as:</para><itemizedlist><listitem><para>The option to include the activation link or not.</para></listitem><listitem><para>The option to semi-automate the approval process. With this option, the admin can pre-approve known email addresses (from student lists, club members,<indexterm><primary>members</primary></indexterm> family and friends etc), see <xref linkend="fig-approve-membership-email-management-1">, <xref linkend="fig-approve-membership-email-management-2">.</para></listitem><listitem><para>If an applicant is on the pre-approved list, his application is automatically approved without the intervention of admin<indexterm><primary>admin</primary></indexterm></para></listitem><listitem><para>If an applicant is not on the approved list, there are various configurations<indexterm><primary>configurations</primary></indexterm> for dealing with the application.<indexterm><primary>application</primary></indexterm></para></listitem><listitem><para>The automated process is configurable from the administration panel (<xref linkend="backend">).</para></listitem></itemizedlist><para>
<figure id="fig-approve-membership-email-management-1">
<title>
E-mail management in the Approve Membership module, part I.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1109;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1109;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1109;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1109;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>E-mail management in the Approve Membership module, part I.</phrase>
</textobject>
<caption>
<para>E-mail management in the Approve Membership module, part I.</para>
</caption>
</mediaobject>
</figure>
</para><para>
<figure id="fig-approve-membership-email-management-2">
<title>
E-mail management in the Approve Membership module, part II.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1110;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1110;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1110;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1110;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>E-mail management in the Approve Membership module, part II.</phrase>
</textobject>
<caption>
<para>E-mail management in the Approve Membership module, part II.</para>
</caption>
</mediaobject>
</figure>
</para><para>If you want users to be registered directly, without confirmation mails, see <xref linkend="register-users-immediately"> or the <ulink url="http://ravenphpscripts.com/download-file-58.html">New User Auto Activation Hack</ulink> and the <ulink url="http://ravenphpscripts.com/download-file-83.html">Auto Registration Activation For Nuke v7.0</ulink>. If you want to disable registration,<indexterm><primary>registration</primary></indexterm> see <xref linkend="disable-registration">.</para></sect2>
<sect2 id="PHP-Nuke-Gallery-module"><title>Gallery module</title><para>The Gallery module from <ulink url="http://www.nukedgallery.net">Nuked Gallery</ulink> is the &ldquo;nuked<indexterm><primary>nuked</primary></indexterm>&rdquo; version of the standalone <ulink url="http://gallery.menalto.com">Gallery</ulink> package. Gallery comes with a handy web based configuration wizard.<indexterm><primary>wizard</primary></indexterm> This wizard helps to make sure that your web server and operating system<indexterm><primary>system</primary></indexterm> are set up correctly. It allows you to configure many of Gallery's options while determining as much as it can from your environment. The wizard will create an administrator account for you. This is a special account that allows you to create other user accounts, create albums,<indexterm><primary>albums</primary></indexterm> and set album permissions.</para><para>
<figure id="fig-gallery">
<title>
Gallery module.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1111;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1111;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1111;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1111;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Gallery module.</phrase>
</textobject>
<caption>
<para>Gallery module.</para>
</caption>
</mediaobject>
</figure>
</para><para>A photo or movie is the basic unit of Gallery.<indexterm><primary>Gallery</primary></indexterm> Photos and movies are grouped together into albums (<xref linkend="fig-gallery">). Once you have the photos in your album,<indexterm><primary>album</primary></indexterm> the fun begins. Typically an intermediate resized version and a thumbnail of the image are created for you. You can:</para><itemizedlist><listitem><para>Add captions<indexterm><primary>captions</primary></indexterm></para></listitem><listitem><para>Edit the thumbnail.<indexterm><primary>thumbnail</primary></indexterm> Gallery comes with a small <application>Java</application> applet that lets you select a part of the image as the source for your thumbnail.<indexterm><primary>thumbnail</primary></indexterm></para></listitem><listitem><para>Rotate your photo (in 90 degree increments)</para></listitem><listitem><para>Highlight a photo (pick a photo to represent the album in the main Gallery)</para></listitem><listitem><para>Reorder the photos in the album </para></listitem><listitem><para>Hide photos (so that they're only visible to the owner)</para></listitem><listitem><para>Delete photos<indexterm><primary>photos</primary></indexterm></para></listitem><listitem><para>Sort your album based on popularity, title, number of comments,<indexterm><primary>comments</primary></indexterm> and photo capture date.<indexterm><primary>date</primary></indexterm> </para></listitem><listitem><para>Edit multiple captions at once </para></listitem></itemizedlist><para>
<figure id="fig-gallery-related-files">
<title>
Gallery related files at nukedgallery.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1112;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1112;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1112;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1112;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Gallery related files at nukedgallery.</phrase>
</textobject>
<caption>
<para>Gallery related files at nukedgallery.</para>
</caption>
</mediaobject>
</figure>
</para><para>To download the Gallery module,<indexterm><primary>module</primary></indexterm> go to <ulink url="http://www.nukedgallery.net">Nuked Gallery</ulink>, find the &ldquo;Related files&rdquo; block (<xref linkend="fig-gallery-related-files">) and click on the link with the most recent stable version. Other Gallery related resources are</para><itemizedlist><listitem><para><ulink url="http://phpnuke.nukedgallery.net">The Nuked Gallery Demo Site</ulink></para></listitem><listitem><para><ulink url="http://gallery.menalto.com/modules.php?op=modload&amp;name=GalleryDocs&amp;file=index&amp;page=gallery1-install.faq.php">The Gallery FAQ</ulink></para></listitem><listitem><para><ulink url="http://gallery.menalto.com/modules.php?op=modload&amp;name=GalleryDocs&amp;file=index">Gallery Documentation</ulink></para></listitem><listitem><para><ulink url="http://gallery.menalto.com/modules.php?op=modload&amp;name=phpWiki&amp;file=index">The Gallery Wiki Docs</ulink></para></listitem><listitem><para><ulink url="http://gallery.menalto.com/modules.php?op=modload&amp;name=PNphpBB2&amp;file=index">The Gallery Forums</ulink></para></listitem></itemizedlist></sect2>
<sect2 id="PHP-Nuke-IP-Tracking-module"><title>IP Tracking module</title><para>
<figure id="fig-ip-tracking">
<title>
IP Tracking module: IP Tracking Info.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1113;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1113;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1113;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1113;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>IP Tracking module: IP Tracking Info.</phrase>
</textobject>
<caption>
<para>IP Tracking module: IP Tracking Info.</para>
</caption>
</mediaobject>
</figure>
</para><para>To track your visitors' IP address, you can use the IP tracking module.<indexterm><primary>module</primary></indexterm> Get it at the <ulink url="http://www.ierealtor.com/modules.php?name=Downloads&amp;d_op=viewdownload&amp;cid=2">Downloads section of ierealtor</ulink>. After installation and activation of the module,<indexterm><primary>module</primary></indexterm> a click on the &ldquo;IP Tracking<indexterm><primary>Tracking</primary></indexterm>&rdquo; link in the Modules block will display the &ldquo;IP Tracking Info&rdquo;, a list of IP addresses that accessed the site (<xref linkend="fig-ip-tracking">). You can order the list by ascending or descending order of its column fields, by clicking on the respective up- and down-arrows.<indexterm><primary>arrows</primary></indexterm></para><tip>
<title>
Lazy man's Logfile Inspection
</title>
<para>
Nothing beats regular inspection of the real web server logfiles - but if you are lazy, you want a quick info of what is going on, or you cannot do otherwise, the IP Tracking module will give you a quick solution to your logfile inspection problem. In the Page View Info (<xref linkend="fig-ip-tracking-page-view-info">), be attentive to URL parameters that pass Javascript code or SQL queries to the database - they are a clear indication of cross-scripting (<xref linkend="cross-site-scripting-with-php-nuke">) and SQL injection (<xref linkend="SQL-injection-with-php-nuke">) attempts at your site respectively.
</para>
</tip>
<para>
<figure id="fig-ip-tracking-page-view-info">
<title>
IP Tracking module: Page View Info.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1114;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1114;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1114;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1114;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>IP Tracking module: Page View Info.</phrase>
</textobject>
<caption>
<para>IP Tracking module: Page View Info.</para>
</caption>
</mediaobject>
</figure>
</para><para>The IP addresses themeselves are links to a detailed view, the &ldquo;Page View Info&rdquo; (<xref linkend="fig-ip-tracking-page-view-info">). It lists the pages that were requested by that IP address. Again, you can order the list by name or date using the arrows on the table header.<indexterm><primary>header</primary></indexterm> Note: administrators won't appear online since they are not entered in the nuke_session table.</para><caution>
<title>
Code corrections necessary for <application>PHP-Nuke</application> v. 6.0 and/or old <acronym>PHP</acronym> versions!
</title>
<para>
If you get the error:
</para>
<blockquote>
<para>
You can&apos;t access this file directly...
</para>
</blockquote>
<para>
then you are using an old <acronym>PHP</acronym> version that does not understand the <ulink url="http://de2.php.net/manual/en/reserved.variables.php">_SERVER superglobal</ulink>. Edit the index.php file of the module and change:
</para>
<screen>
<![CDATA[
if (!eregi("modules.php", $_SERVER['PHP_SELF'])) {
]]>
</screen>
<para>
to:
</para>
<screen>
<![CDATA[
if (!eregi("modules.php", $PHP_SELF)) {
]]>
</screen>
<para>
You also have to edit iptracking.php. Change:
</para>
<screen>
<![CDATA[
$ip = $_SERVER["REMOTE_ADDR"] ;
]]>
</screen>
<para>
to:
</para>
<screen>
<![CDATA[
$ip = $HTTP_SERVER_VARS["REMOTE_ADDR"] ;
]]>
</screen>
<para>
and
</para>
<screen>
<![CDATA[
$pg = $_SERVER["SCRIPT_NAME"];
]]>
</screen>
<para>
to:
</para>
<screen>
<![CDATA[
$pg = $HTTP_SERVER_VARS["SCRIPT_NAME"];
]]>
</screen>
<para>
and
</para>
<screen>
<![CDATA[
if (($_SERVER["QUERY_STRING"]) != "")
{ $pg = $pg . "?" . $_SERVER["QUERY_STRING"] ; }
]]>
</screen>
<para>
to:
</para>
<screen>
<![CDATA[
if (($HTTP_SERVER_VARS["QUERY_STRING"]) != "")
{ $pg = $pg . "?" . $HTTP_SERVER_VARS["QUERY_STRING"] ; }
]]>
</screen>
<para>
If you are getting MySQL errors like the one of <xref linkend="Warning-mysql-fetch-row-supplied-argument">, complaining about non-valid MySQL result resources, then you are probably using an old <application>PHP-Nuke</application> version (like 6.0, for example) that uses the field &ldquo;username&rdquo;, instead of &ldquo;uname&rdquo; in the nuke_session table. In this case you have to change &ldquo;uname&rdquo; to &ldquo;username&rdquo; in the two WHERE clauses of the index.php file of the module. Change:
</para>
<screen>
<![CDATA[
$res = sql_query("select * from ".$prefix."_session
where uname='$username' and host_addr='$ip'", $dbi);
]]>
</screen>
<para>
to:
</para>
<screen>
<![CDATA[
$res = sql_query("select * from ".$prefix."_session
where username='$username' and host_addr='$ip'", $dbi);
]]>
</screen>
<para>
and
</para>
<screen>
<![CDATA[
$res2 = sql_query("select * from ".$prefix."_session
where host_addr='$ip' and host_addr=uname", $dbi);
]]>
</screen>
<para>
to:
</para>
<screen>
<![CDATA[
$res2 = sql_query("select * from ".$prefix."_session
where host_addr='$ip' and host_addr=username", $dbi);
]]>
</screen>
</caution>
<para>If your main motivation for using the IP tracking module is to be able to ban certain annoying visitors from certain IPs, check also the Protector<indexterm><primary>Protector</primary></indexterm> module (<xref linkend="PHP-Nuke-Protector-module">) for a ready-made, full-featured solution to IP banning,<indexterm><primary>banning</primary></indexterm> as well as <xref linkend="ban-IP-addresses"> for a quick, do-it-yourself hack.<indexterm><primary>hack</primary></indexterm></para></sect2>
<sect2 id="PHP-Nuke-Protector-module"><title>Protector module</title><para>The <ulink url="http://protector.warcenter.se/index.php">Protector System</ulink> gives you &quot;high level&quot; logs of session activity on your <application>PHP-Nuke</application> site. But not only this - it can be effectively used to ban IP addresses and users:</para><itemizedlist><listitem><para>Possibility to add a single IP or a whole range.<indexterm><primary>range</primary></indexterm></para></listitem><listitem><para>Logging of ALL IP(s) that hit your <application>PHP-Nuke</application> site.</para></listitem><listitem><para>If a member joins the site the logger fetches the username and stores it with their IP.<indexterm><primary>IP</primary></indexterm> (Otherwise the IP gets the username Anonymous)</para></listitem><listitem><para>If a member IP changes the new IP will be stored with their username<indexterm><primary>username</primary></indexterm></para></listitem><listitem><para>Logging of the real IP not just the proxy IP if that is the case.<indexterm><primary>case</primary></indexterm></para></listitem><listitem><para>Search function (with wildcards *) after the logged IP and user name. And sort order.</para></listitem><listitem><para>Protection of your IP is done when you first install this system.<indexterm><primary>system</primary></indexterm> That means that no one can ban that IP.<indexterm><primary>IP</primary></indexterm></para></listitem><listitem><para>As head admin (GOD) you can add several protected IP(s) in the Admin Panel. All other admins just see personal settings where they can change total amount of row they want to display in the banned &amp; locate IP panels.</para></listitem><listitem><para>Automaticallyupdate the date of a logged IP so that you can see when a particular IP or user was on your site.</para></listitem><listitem><para>You can dns/trace/ping and more after you query the IP with the query tool that I have implemented.</para></listitem><listitem><para>It is totally themes integrated system.<indexterm><primary>system</primary></indexterm></para></listitem><listitem><para>Security check so that you can't ban yourself (the IP you currently use when your in the admin panel) or protected IP.<indexterm><primary>IP</primary></indexterm></para></listitem><listitem><para>Double check so that there is no banning or logging of the same information<indexterm><primary>information</primary></indexterm> twice.</para></listitem><listitem><para>If a banned member is banned and they change their IP.<indexterm><primary>IP</primary></indexterm> The system will check the banned database and compare if the username(s) match.<indexterm><primary>match</primary></indexterm> If it does a new row with the new IP and same username is added in the ban list. So they are banned again automatically with the new IP.<indexterm><primary>IP</primary></indexterm></para></listitem><listitem><para>Counts on how many times a banned user is trying to reach the site.</para></listitem><listitem><para>Possibility to instantly ban people from your list with logged IP.<indexterm><primary>IP</primary></indexterm></para></listitem><listitem><para>You can of course un-ban IP numbers.</para></listitem><listitem><para>Very simple to install, The Ban System will create all needed tables for the MySQL Database on the first run.</para></listitem><listitem><para>As Forum admin can you reach the Edit User Function from the &quot;Locate Panel&quot;. Also, a direct link to the public user information is there.</para></listitem><listitem><para>In the Locate panel there are 4 different images close to the IP number.</para><orderedlist><listitem><para><indexterm><primary>Enumerate</primary></indexterm>A Green dot indicates that the IP is just logged.</para></listitem><listitem><para><indexterm><primary>Enumerate</primary></indexterm>A Red dot indicates that IP is banned.<indexterm><primary>banned</primary></indexterm></para></listitem><listitem><para><indexterm><primary>Enumerate</primary></indexterm>A Star indicates that this IP number is the IP you are currently using.</para></listitem><listitem><para><indexterm><primary>Enumerate</primary></indexterm>A blinking computer gif indicates if that logged user/IP is online.</para></listitem></orderedlist></listitem><listitem><para>A small stat page where you can see some stats on the Ban Protector System.</para></listitem><listitem><para>Anti hammering protection system.<indexterm><primary>system</primary></indexterm></para></listitem><listitem><para>Special Notes to each logged IP is possible.</para></listitem><listitem><para>Close the site function.<indexterm><primary>function</primary></indexterm> Only admins are able to be on the site when active.</para></listitem><listitem><para>When a user attempts to access the admin page a note is added to their IP<indexterm><primary>IP</primary></indexterm> to warn you of potential hackers.<indexterm><primary>hackers</primary></indexterm></para></listitem><listitem><para>An auto pruning system to prune logged IP addresses set from the maintenance<indexterm><primary>maintenance</primary></indexterm> panel.<indexterm><primary>panel</primary></indexterm></para></listitem><listitem><para>Grant access to the Ban System for your (admin) users who are not a &quot;super user&quot;.</para></listitem><listitem><para>Auto Protect your IP if you logon using another pc with your user name and the old IP will be replaced with the new one until you logon again then your IP will be replaced again.</para></listitem><listitem><para>Optimize and repair the tables in the Protector System to reclaim the unused space and to de-fragment the data file or if you get errors.</para></listitem></itemizedlist></sect2>
<sect2 id="PHP-Nuke-WebCam-module"><title>WebCam module</title><para>
<figure id="fig-camPortal-block">
<title>
camPortal block.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1115;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1115;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1115;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1115;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>camPortal block.</phrase>
</textobject>
<caption>
<para>camPortal block.</para>
</caption>
</mediaobject>
</figure>
</para><para>If you are looking for a webcam module,<indexterm><primary>module</primary></indexterm> have a look at the <ulink url="http://www.skepticshour.com/portal.php?load=Descargas&amp;file=view_downloads&amp;func=view_downloads&amp;cid=5">camPortal</ulink>. See it in action at <ulink url="http://www.skepticshour.com/portal.php?load=camPortal">The Sceptics Hour</ulink>. camPortal's highlights include:</para><itemizedlist><listitem><para>Advanced Admin panel<indexterm><primary>panel</primary></indexterm></para></listitem><listitem><para>Static or Dynamic webcam image in block (optional, see <xref linkend="fig-camPortal-block">)</para></listitem><listitem><para>Categories<indexterm><primary>Categories</primary></indexterm></para></listitem><listitem><para>Vote system (<xref linkend="fig-camPortal">)</para></listitem><listitem><para>Comment system<indexterm><primary>system</primary></indexterm></para></listitem><listitem><para>Hit counter<indexterm><primary>counter</primary></indexterm></para></listitem><listitem><para>Users can report broken cams</para></listitem><listitem><para>Users can submit their cams</para></listitem><listitem><para>Languages included: English,<indexterm><primary>English</primary></indexterm> Spanish, Dutch, German.</para></listitem></itemizedlist><para>
<figure id="fig-camPortal">
<title>
camPortal module.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1116;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1116;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1116;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1116;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>camPortal module.</phrase>
</textobject>
<caption>
<para>camPortal module.</para>
</caption>
</mediaobject>
</figure>
</para><para>You must have at least <application>PHP-Nuke</application> 6.5 and a newer <acronym>PHP</acronym> version (one that understands the <ulink url="http://de2.php.net/manual/en/reserved.variables.php">_SERVER superglobal</ulink>, for example) to use this module. The installation instructions are a bit outdated. In some parts, for example, they talk about &ldquo;webcam&rdquo;, when atually it should say &ldquo;camPortal&rdquo; - but with knowledge of the structure of a <application>PHP-Nuke</application> module (see <xref linkend="module-structure">) you will figure it out. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
<para>To grab the images from your webcam,<indexterm><primary>webcam</primary></indexterm> you can use <ulink url="http://www.theill.com/conquercam/default.asp">ConquerCam</ulink>. ConquerCam is a low-priced (only $10 USD), easy to use webcam manager for grabbing images from your web cam under Windows,<indexterm><primary>Windows</primary></indexterm> preparing them with various effects and uploading them to your web site (where you can use camPortal<indexterm><primary>camPortal</primary></indexterm> to display them in PHP-Nuke). Using ConquerCam you are able to setup your computer as a security system<indexterm><primary>system</primary></indexterm> as well, using the advanced motion detection and mail-notification system<indexterm><primary>system</primary></indexterm> included.</para><para>
<figure id="fig-conquercam">
<title>
ConquerCam: main window with the Options dialog opened up.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1117;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1117;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1117;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1117;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>ConquerCam: main window with the Options dialog opened up.</phrase>
</textobject>
<caption>
<para>ConquerCam: main window with the Options dialog opened up.</para>
</caption>
</mediaobject>
</figure>
</para><para>ConquerCam can be customized in a variety of ways, e.g. by selecting how often you want to grab and upload images, which overlay<indexterm><primary>overlay</primary></indexterm> effects you want to use (many of the well-known Adobe PhotoShop effects are available, such as Multiply or Darken) and unlimited numbers of textual captions to put on your grabbed image using a bunch of tags. Tags are replaced by dynamic data such as current date/time, WinAMP title<indexterm><primary>title</primary></indexterm> currently playing or the Swatch Internet Time.</para></sect2>
<sect2 id="PHP-Nuke-My-Headlines-module"><title>My Headlines module</title><para>
<figure id="fig-myheadlines-box">
<title>
MyHeadlines Box containing syndicated content.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1118;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1118;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1118;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1118;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>MyHeadlines Box containing syndicated content.</phrase>
</textobject>
<caption>
<para>MyHeadlines Box containing syndicated content.</para>
</caption>
</mediaobject>
</figure>
</para><para>MyHeadlines is a personalized syndicated content module.<indexterm><primary>module</primary></indexterm> As a user you may subscribe to many news/content sources from the MyHeadlines<indexterm><primary>MyHeadlines</primary></indexterm> database.<indexterm><primary>base</primary></indexterm> For each of your subscriptions this site will gather the latest headlines/stories/content from the source and present a consolidated view of all of your interests in one location. The MyHeadlines engine allows you to configure the layout of this page to suit your needs; It will allow you to place the &quot;Boxes&quot; containing the syndicated content (<xref linkend="fig-myheadlines-box">) in any one of three possible places (Left, Right or Middle) on two rows (Top and Bottom) of the module's space on the front page.</para><para>
<figure id="fig-myheadlines-subscribe">
<title>
MyHeadlines: Subscribing to News sources.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1119;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1119;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1119;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1119;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>MyHeadlines: Subscribing to News sources.</phrase>
</textobject>
<caption>
<para>MyHeadlines: Subscribing to News sources.</para>
</caption>
</mediaobject>
</figure>
</para><para>There are over 1000 sources in the MyHeadlines database:<indexterm><primary>base</primary></indexterm> from special interest groups, to regional news,<indexterm><primary>news</primary></indexterm> to technology sites, to company/corporation specific news,<indexterm><primary>news</primary></indexterm> and more. You can subscribe to the content you want. As an added bonus, MyHeadlines now sports a Stock Ticker &quot;Box&quot; that will allow you to watch your favourite Index,<indexterm><primary>Index</primary></indexterm> Stock, Bond, etc.</para><para>Download it from the <ulink url="http://www.jmagar.com/modules.php?op=modload&amp;name=Downloads&amp;file=index&amp;req=viewdownload&amp;cid=5">Downloads section of jmagar.com</ulink>. See also the <ulink url="http://www.jmagar.com/modules.php?op=modload&amp;name=FAQ&amp;file=index&amp;myfaq=yes&amp;id_cat=6&amp;categories=About&amp;parent_id=1">MyHeadlines FAQ</ulink>. See it in action at <ulink url="http://www.jmagar.com">jmagar</ulink> and <ulink url="http://www.weenor.com/index.php?module=MyHeadlines&amp;func=view">weenor</ulink>.</para></sect2>
<sect2 id="PHP-Nuke-Tools-module"><title>PHP-Nuke-Tools module </title><para>
<figure id="fig-php-nuke-tools-block">
<title>
<application>PHP-Nuke</application> Tools block
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1120;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1120;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1120;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1120;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>PHP-Nuke Tools block</phrase>
</textobject>
<caption>
<para>PHP-Nuke Tools block</para>
</caption>
</mediaobject>
</figure>
</para><para>The <ulink url="http://www.disipal.net/modules.php?name=Downloads&amp;d_op=viewdownloaddetails&amp;lid=119&amp;title=PHP-Nuke%20Tools%20v3.00">PHP-Nuke Tools module</ulink> is one of the most helpful modules.<indexterm><primary>modules</primary></indexterm> Whether you are developing for <application>PHP-Nuke</application> or want to write a module or block<indexterm><primary>block</primary></indexterm> really quickly, or even if you just want to learn how modules,<indexterm><primary>modules</primary></indexterm> blocks and the rest works in PHP-Nuke, you will appreciate its help.. It offers features such as:</para><itemizedlist><listitem><para>Module Creator (see <xref linkend="fig-php-nuke-tools-module-creator">), </para></listitem><listitem><para>Block Creator, </para></listitem><listitem><para>Help for Module Creator, </para></listitem><listitem><para>Help for Block Creator, </para></listitem><listitem><para>HTML to PHP,<indexterm><primary>PHP</primary></indexterm> </para></listitem><listitem><para>HTML to ASP, </para></listitem><listitem><para>HTML to JSP,<indexterm><primary>JSP</primary></indexterm> </para></listitem><listitem><para>HTML to Perl,<indexterm><primary>Perl</primary></indexterm> </para></listitem><listitem><para>HTML to JavaScript,<indexterm><primary>JavaScript</primary></indexterm> </para></listitem><listitem><para>Online HTML Editor, </para></listitem><listitem><para>Meta Tag Creator, </para></listitem><listitem><para>Scrollbar Creator, </para></listitem><listitem><para>Popup Creator, </para></listitem><listitem><para>Hex Colors</para></listitem></itemizedlist><para>
<figure id="fig-php-nuke-tools-module-creator">
<title>
<application>PHP-Nuke</application> Tools module: Module Creator.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1121;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1121;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1121;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1121;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>PHP-Nuke Tools module: Module Creator.</phrase>
</textobject>
<caption>
<para>PHP-Nuke Tools module: Module Creator.</para>
</caption>
</mediaobject>
</figure>
</para><para>and many others. It comes with an extra block containing links to all functions (<xref linkend="fig-php-nuke-tools-block">). See it in action at <ulink url="http://www.disipal.net">disipal.net</ulink>.</para><tip>
<title>
Especially recommended for beginners (but not only)!
</title>
<para>
You are a beginner in PHP(-Nuke), have just started your very first module or block, but you get errors and don't understand why? Give it a try with the <application>PHP-Nuke</application> Tools Module or Block Creator! It will help you see what you were missing and will also give you a feeling of how code looks before and after it is "nuked".
<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_cool.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_cool.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_cool.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_cool.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject>
</para>
</tip>
<para>For a much more ambitious project on automatic building of <application>PHP-Nuke</application> blocks and modules (towards a web-based integrated programming environment, IDE,<indexterm><primary>IDE</primary></indexterm> for PHP-Nuke) ckeck <ulink url="http://ravenphpscripts.ravenwebhosting.com/BlockBuilder">Raven's Block Builder</ulink>. It is currently under development,<indexterm><primary>development</primary></indexterm> but very promising.</para></sect2>
<sect2 id="PHP-Nuke-Upload-module"><title>Upload module</title><para>
<figure id="fig-upload">
<title>
Upload module.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1122;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1122;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1122;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1122;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Upload module.</phrase>
</textobject>
<caption>
<para>Upload module.</para>
</caption>
</mediaobject>
</figure>
</para><para>The <ulink url="http://trainsim.condor-edv.com/nuke-upload">PHP-Nuke Upload module</ulink> facilitates upload functionality for <application>PHP-Nuke</application> and has the following features:<indexterm><primary>features</primary></indexterm></para><itemizedlist><listitem><para>Upload to virtual folders</para></listitem><listitem><para>Download the files from these folders</para></listitem><listitem><para>List files in these folders</para></listitem><listitem><para>Possibly add a comment to each file</para></listitem><listitem><para>Use the same filename several times in one folder</para></listitem><listitem><para>Each file is owned by one registered user. </para></listitem><listitem><para>Each directory is owned by one registered user. </para></listitem><listitem><para>Only the adminstrator can create new folders and assign them to a registered<indexterm><primary>registered</primary></indexterm> user</para></listitem><listitem><para>The adminstrator can change the ownership a existing file or folder</para></listitem><listitem><para>The owner of a file can change the permissions on the file</para></listitem><listitem><para>When uploading to a folder, the uploader (only registered users are allowed to upload files) may choose the initial permissions on the new file. </para></listitem><listitem><para>The following permissions exist for owner and registered users: no permission,<indexterm><primary>permission</primary></indexterm> read permission, read/write permission.<indexterm><primary>permission</primary></indexterm> Also a flag is available, that allows direct download access for anonymous<indexterm><primary>anonymous</primary></indexterm> users (but nothing more) </para></listitem><listitem><para>Full group membership access:<indexterm><primary>access</primary></indexterm> Each registered user can be a member of multiple groups, and each file can belong to one group, which allows no/read/read+write access (configurable for each file) </para></listitem><listitem><para>Multiple Language support</para></listitem><listitem><para>Most links may also include images, to give the module a pretty layout.<indexterm><primary>layout</primary></indexterm></para></listitem><listitem><para>Size display for each file</para></listitem><listitem><para>Download counter for each file</para></listitem><listitem><para>Quota support based on group, user and folder quotas.<indexterm><primary>quotas</primary></indexterm></para></listitem><listitem><para>Optional thumbnail support for .jpg and .gif files based on the original files (so this is only a pseudo thumbnail at the moment). </para></listitem></itemizedlist><important>
<title>
PHP-Nuke versions greater than 6.5 and the Upload module
</title>
<para>
If you are using a version of <application>PHP-Nuke</application> greater than 6.5, you must do a minimal, but crucial, change in the index.php file of the Upload file. Otherwise, the SQL queries will use the wrong field (uid, instead of user_id) for the user in the nuke_users table, leading to errors. Find the line
</para>
<screen>
<![CDATA[if ($Version_Num == "6.5") {]]>
</screen>
<para>
and change it to:
</para>
<screen>
<![CDATA[if ($Version_Num >= "6.5") {]]>
</screen>
<para>
This will make sure that the right field names are used for all versions greater or equal to 6.5, not only for the 6.5 version.
<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject>
</para>
</important>
</sect2>
<sect2 id="Upload-add-on-for-phpBB"><title>Upload add-on for phpBB</title><para>If you are interested in an Upload add-on for your phpBB Forums, then you can check <ulink url="http://smartor.is-root.com/viewtopic.php?t=3021">Photo Album Addon</ulink>. This is a phpBB-based photo album/gallery management system. It is really powerful, stable, efficient, rich in features and highly customizable. The version 2 was written from the scratch for more security, performance, etc. It is not really a modification or hack, it is rather a phpBB-based system. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_smile.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_smile.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_smile.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_smile.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
<para>Features:</para><itemizedlist><listitem><para>Fully integrated with phpBB2 backend (DB, session,<indexterm><primary>session</primary></indexterm> template, multi languages, etc.)</para></listitem><listitem><para>Powerful and handy Admin Control Panel</para></listitem><listitem><para>Auto-generated thumbnail s(requires GD)</para></listitem><listitem><para>Manual-uploaded thumbnails (for those who don't have the GD library<indexterm><primary>library</primary></indexterm><footnote><para>To find out if you have the GD library loaded, run a test script like test.php (see <xref linkend="test-php">), ConnectTest.php (see <xref linkend="ConnectTest-php">) or analyze.<indexterm><primary>analyze</primary></indexterm>php (see <xref linkend="analyze-php">).</para></footnote>)</para></listitem><listitem><para>Thumbnail cache (for better performance)</para></listitem><listitem><para>Multi-categories<indexterm><primary>Multi-categories</primary></indexterm></para></listitem><listitem><para>Powerful and phpBB-like permissions system<indexterm><primary>system</primary></indexterm></para></listitem><listitem><para>Moderator Control Panel</para></listitem><listitem><para>Upload Quotas</para></listitem><listitem><para>Pictures Description</para></listitem><listitem><para>Recent pics</para></listitem><listitem><para>Personal galleries (for member-oriented boards)</para></listitem><listitem><para>Rate system<indexterm><primary>system</primary></indexterm></para></listitem><listitem><para>Comment system<indexterm><primary>system</primary></indexterm></para></listitem><listitem><para>Hot link prevention (can set allowed domains<indexterm><primary>domains</primary></indexterm><footnote><para>See <xref linkend="make-PHP-Nuke-hot-link-stealth"> for a do-it-yourself solution to hot link prevention.<indexterm><primary>prevention</primary></indexterm></para></footnote>)</para></listitem><listitem><para>Auto-optimization for different GD versions</para></listitem><listitem><para>Pic view counter<indexterm><primary>counter</primary></indexterm></para></listitem><listitem><para>Admin/Moderator pic approval<indexterm><primary>approval</primary></indexterm></para></listitem><listitem><para>Probably uploadable in <acronym>PHP</acronym> Safe Mode</para></listitem></itemizedlist><warning>
<title>
May not work with every <application>PHP-Nuke</application> version!
</title>
<para>
The Photo Album is an add-on for the standalone phpBB Forums. It has been ported to <application>PHP-Nuke</application> with the Album module (see the <ulink url="http://www.portedmods.com/modules.php?name=Downloads&amp;d_op=viewdownload&amp;cid=42">Admin Panel Downloads Category of portedmods</ulink>). This module was only tested with <application>PHP-Nuke</application> 6.5RC2 with phpbb module 2.1 and does not work on a site with the 2.0.6b version of the phpBB module!
</para>
</warning>
<para>For yet another file attachment add-on to the <application>PHP-Nuke</application> phpBB Forums, see the &ldquo;Attachment Mod&rdquo; from the <ulink url="http://www.portedmods.com/modules.php?name=Downloads&amp;d_op=viewdownload&amp;cid=43">PHP-Nuke 6.5 / Ported Mods / Extra</ulink> Downloads section of portedmods. See <ulink url="http://www.portedmods.com/modules.php?name=Forums&amp;file=viewtopic&amp;t=241">File Attachment Mod v2.3.6 for phpnuke6 with 2.06</ulink> for a complete list of its features.<indexterm><primary>features</primary></indexterm> For a discussion thread on Upload modules,<indexterm><primary>modules</primary></indexterm> see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=290">I cant find this Upload module</ulink>.</para></sect2>
<sect2 id="php-nuke-ODP-module"><title>ODP module</title><para>
<figure id="fig-odp">
<title>
ODP module.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1123;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1123;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1123;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1123;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>ODP module.</phrase>
</textobject>
<caption>
<para>ODP module.</para>
</caption>
</mediaobject>
</figure>
</para><para>The <ulink url="http://www.complex-berlin.de/download.php?op=getit&amp;lid=391">ODP module</ulink> displays the popular <ulink url="http://dmoz.org">Open Directory</ulink> inside your <application>PHP-Nuke</application> site (<xref linkend="fig-odp">). It is based on the <ulink url="http://www.bie.no/products/phpodp">phpodp class</ulink>. The whole functionality is encapsulated in the phpodp class in odp.php.<indexterm><primary>odp.php</primary></indexterm> The <application>PHP-Nuke</application> module practically only calls the odp.php script.</para><para>If you would like to import all links of an ODP category into your Web Links<indexterm><primary>Web Links</primary></indexterm> or Downloads module,<indexterm><primary>module</primary></indexterm> have a look in <xref linkend="enter-thousands-of-web-links"> and <xref linkend="enter-thousands-of-download-links"> respectively for some interesting procedures.</para></sect2>
<sect2 id="PHP-Nuke-eCommerce-module"><title>eCommerce module</title><para>There is certainly a lot going on currently in the area of eCommerce and <application>PHP-Nuke</application>. However, a ready-to-use <application>PHP-Nuke</application> port of the well-known <ulink url="http://www.oscommerce.com">osCommerce</ulink> has yet to hit the streets. Keep an eye on the following promising links:</para><itemizedlist><listitem><para><ulink url="http://www.osc2nuke.org">osc2Nuke</ulink>: The international project of merging osCommerce and <application>PHP-Nuke</application>. With links to national projects worldwide.</para></listitem><listitem><para><ulink url="http://sourceforge.net/projects/multishop">Multishop</ulink>: &ldquo;We depart from the CMS PhpNuke and osCommerce to realize a virtual mall, a central portal where different shop, with all the funcionalities of a traditional eCommerce site (customer accounts,address book for different shipping,Order history,<indexterm><primary>history</primary></indexterm>..),converge&rdquo;, the developers say.</para></listitem><listitem><para><ulink url="http://www.splatt.it/article1087.html">OSCommerce gets a Nuke-Module: a new SourceForge-Projects starts now!</ulink></para></listitem></itemizedlist><para>
<figure id="fig-calloways-cart-add-product">
<title>
Calloways Cart module: Add Product screen.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1124;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1124;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1124;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1124;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Calloways Cart module: Add Product screen.</phrase>
</textobject>
<caption>
<para>Calloways Cart module: Add Product screen.</para>
</caption>
</mediaobject>
</figure>
</para><para>For the moment, you could try <ulink url="http://www.theguitarfiles.com/CC/CallowaysCart">CallowaysCart</ulink>, a shopping cart recently released under the GPL and especially designed for <application>PHP-Nuke</application> (all versions) and <ulink url="http://www.paypal.com">Paypal</ulink>'s payment service (<xref linkend="fig-calloways-cart-add-product">).</para><para>A commercial (but with $35 USD certainly not expensive) eCommerce solution for <application>PHP-Nuke</application> is <ulink url="http://www.burnwave.com">Emporium</ulink>. The following is an incomplete list of its features,<indexterm><primary>features</primary></indexterm> but bear in mind that, since Emporium is under active and rapid development,<indexterm><primary>development</primary></indexterm> it will be outdated by the time you read this:</para><itemizedlist><listitem><para>Unlimited Products.</para></listitem><listitem><para>Unlimited Categories.<indexterm><primary>Categories</primary></indexterm></para></listitem><listitem><para>Unlimited Brands to associate Products with Modularized Payment/Shipping methods.</para></listitem><listitem><para>Unlimited currencies.<indexterm><primary>currencies</primary></indexterm></para></listitem><listitem><para>Automated currency conversions (using Yahoo,<indexterm><primary>Yahoo</primary></indexterm> XE, Oanda services).</para></listitem><listitem><para>Unlimited Product Options for Products (radio,<indexterm><primary>radio</primary></indexterm> dropdown, multidropdown, checkbox, textfield,<indexterm><primary>textfield</primary></indexterm> textarea, inclusive [hidden], etc).</para></listitem><listitem><para>Unlimited Product Media for Products.</para></listitem><listitem><para>Tax classing (unlimited class types, associated with particular products... assign certain locations [states, countries] to tax classing with different tax structures).</para></listitem></itemizedlist><para>Instead of relying on a feature list, a better idea might be to test Emporium:<indexterm><primary>Emporium</primary></indexterm> you can go to the <ulink url="http://demo.burnwave.com">Emporium demo site</ulink> ([admin:<indexterm><primary>admin</primary></indexterm> demo, pass: demo]), and have full access to Emporium and all of its features.<indexterm><primary>features</primary></indexterm> </para></sect2>
<sect2 id="PHP-Nuke-WorkBoard-module"><title>WorkBoard Module</title><para>
<figure id="fig-workboard">
<title>
Administration panel: WorkBoard.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1125;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1125;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1125;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1125;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: WorkBoard.</phrase>
</textobject>
<caption>
<para>Administration panel: WorkBoard.</para>
</caption>
</mediaobject>
</figure>
</para><para><ulink url="http://www.burnwave.com/modules.php?name=Archives">WorkBoard</ulink> is a <application>PHP-Nuke</application> module for Project Management, distributed under the GNU<indexterm><primary>GNU</primary></indexterm> General Public Licence.<indexterm><primary>Licence</primary></indexterm></para><para>To install WorkBoard,<indexterm><primary>WorkBoard</primary></indexterm> </para><itemizedlist><listitem><para>Extract the archive and upload all files from directory 'html' to your root<indexterm><primary>root</primary></indexterm> <application>PHP-Nuke</application> directory.</para></listitem><listitem><para>Insert sql/workboard.sql into your database,<indexterm><primary>base</primary></indexterm> or</para></listitem><listitem><para>Copy 'wb_install.php' from directory 'installation' into your root <application>PHP-Nuke</application> directory, and then run script from your browser. Follow the instructions presented to you.</para></listitem></itemizedlist><para>Once installed, a click on the WorkBoard icon in the administration panel<indexterm><primary>panel</primary></indexterm> (<xref linkend="fig-workboard">) leads to the WorkBoard administration panel (<xref linkend="fig-workboard-admin">). There, you can set up </para><itemizedlist><listitem><para>Projects and project positions.</para></listitem><listitem><para>Tasks and task statuses and priorities.</para></listitem><listitem><para>Project members<indexterm><primary>members</primary></indexterm></para></listitem></itemizedlist><para>
<figure id="fig-workboard-admin">
<title>
WorkBoard module: Administration panel.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1126;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1126;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1126;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1126;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>WorkBoard module: Administration panel.</phrase>
</textobject>
<caption>
<para>WorkBoard module: Administration panel.</para>
</caption>
</mediaobject>
</figure>
</para><para>The WorkBoard module is still under rapid development.<indexterm><primary>development</primary></indexterm></para></sect2>
</sect1>
</chapter>
<chapter id="architecture"><title>Architecture and structure </title><para>The structure of <application>PHP-Nuke</application> is organized into modules,<indexterm><primary>modules</primary></indexterm> all the files are managed by other files that are located in the <application>PHP-Nuke</application> root directory and include, according to the parameters passed to them, the intended module.<indexterm><primary>module</primary></indexterm></para><para>These tasks are carried out from only 3 pages:</para><itemizedlist><listitem><para>index.<indexterm><primary>index</primary></indexterm>php : In order to display the main page</para></listitem><listitem><para>modules.<indexterm><primary>modules</primary></indexterm>php : In order to include the internal modules.<indexterm><primary>modules</primary></indexterm></para></listitem><listitem><para>admin.php : In order to include the administration interface.<indexterm><primary>interface</primary></indexterm></para></listitem></itemizedlist><para>It's not possible to call a module by calling a direct path to it. This is so in order to make installation easier, render the graphics management<indexterm><primary>management</primary></indexterm> more independent (otherwise we would have to change the path of the images<indexterm><primary>images</primary></indexterm> each time we position ourselves in an internal directory), have only a few files in the root directory and render the system more secure. </para><para>Everything is being called, as we said, through URL parameters (strings) passed to the &ldquo;modules.<indexterm><primary>modules</primary></indexterm>php&rdquo; file which specify which files are to be included. If for example we want to call the Topics module,<indexterm><primary>module</primary></indexterm> the string to be passed should be:</para><screen><![CDATA[http://www.yoursite.com/modules.php?name=Topics
]]></screen><para>The command that is sent this way is &quot;includes in the page created by modules.<indexterm><primary>modules</primary></indexterm>php the output of the file index.<indexterm><primary>index</primary></indexterm>php that is found in the folder modules/Topics/&quot;.</para><para>The other files present in the <application>PHP-Nuke</application> root directory are:</para><itemizedlist><listitem><para>auth.php: Manages authentication through the cookies.<indexterm><primary>cookies</primary></indexterm></para></listitem><listitem><para>mainfile.php: Contains all the necessary functions for the management of PHP-Nuke</para></listitem><listitem><para>header.php: manages the variables that are related to the header (inclusion of metatags,<indexterm><primary>metatags</primary></indexterm> Javascript...)</para></listitem><listitem><para>footer.php: variables related to the footer.<indexterm><primary>footer</primary></indexterm></para></listitem><listitem><para>backend.php: manages the output of the news that can be captured from other sites</para></listitem><listitem><para>ultramode.txt: ditto<indexterm><primary>ditto</primary></indexterm></para></listitem><listitem><para>robots.txt: contains instructions for the search engines informing them which folders not to index<indexterm><primary>index</primary></indexterm></para></listitem></itemizedlist><sect1 id="directory-structure"><title>Directory structure </title><para>The html folder of <application>PHP-Nuke</application> contains the following directories and files (<xref linkend="fig-php-nuke-html-folder">):</para><para>
<figure id="fig-php-nuke-html-folder">
<title>
<application>PHP-Nuke</application> directory structure.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1127;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1127;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1127;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1127;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>PHP-Nuke directory structure.</phrase>
</textobject>
<caption>
<para>PHP-Nuke directory structure.</para>
</caption>
</mediaobject>
</figure>
</para><variablelist><varlistentry><term>admin:<indexterm><primary>admin</primary></indexterm>
</term><listitem><para>Contains 4 subdirectories (links, language, case, modules) that manage the various administration modules.<indexterm><primary>modules</primary></indexterm> The folder that accommodates the operating files is modules/admin/.</para></listitem></varlistentry><varlistentry><term>robots.<indexterm><primary>robots</primary></indexterm>txt:
</term><listitem><para>Contains instructions for search engines. PHP-Nuke's default robots.<indexterm><primary>robots</primary></indexterm>txt file contains the following:</para><screen><![CDATA[User-agent: *
]]><![CDATA[Disallow: admin.php
]]><![CDATA[Disallow: /admin/
]]><![CDATA[Disallow: /images/
]]><![CDATA[Disallow: /includes/
]]><![CDATA[Disallow: /themes/
]]><![CDATA[Disallow: /blocks/
]]><![CDATA[Disallow: /modules/
]]><![CDATA[Disallow: /language/
]]></screen><para>This means that if a search engine visits the site, it should not index<indexterm><primary>index</primary></indexterm> the folders mentioned. You can also insert other instructions in the robots.<indexterm><primary>robots</primary></indexterm>txt file, for example disallow a certain search engine:<indexterm><primary>engine</primary></indexterm></para><screen><![CDATA[User-agent: ArchitextSpider
]]><![CDATA[Disallow: /
]]></screen><para>In this example, we forbid Excite's spider from indexing the site. However, our instructions will have no effect on a spider that does not honour the robots.<indexterm><primary>robots</primary></indexterm>txt file. Some aggressive spiders are known for being notorious and not obeying to our instructions in robots.<indexterm><primary>robots</primary></indexterm>txt. You could try to redirect them to an error page through a test on their IP address, User-agent string or some other criterium using mod_rewrite<indexterm><primary>rewrite</primary></indexterm> (see <xref linkend="mod-rewrite">). Please note that the User-agent string can be easily faked.<indexterm><primary>faked</primary></indexterm></para></listitem></varlistentry><varlistentry><term>blocks:
</term><listitem><para>Contains all the block files for all of our available blocks. </para></listitem></varlistentry><varlistentry><term>images:<indexterm><primary>images</primary></indexterm>
</term><listitem><para>Contains all the images relating to PHP-Nuke, for example in the folder &ldquo;topics<indexterm><primary>topics</primary></indexterm>&rdquo; we will find archived the images of the topics that will appear in the news,<indexterm><primary>news</primary></indexterm> in &ldquo;banners<indexterm><primary>banners</primary></indexterm>&rdquo; all banners in rotation etc...</para></listitem></varlistentry><varlistentry><term>includes<indexterm><primary>includes</primary></indexterm>:
</term><listitem><para>Here are all the files that are necessary to particular management situations,<indexterm><primary>ations</primary></indexterm> these files do not work independently but are included in other files, mainly in mainfile.php and header.php. The files are:</para><itemizedlist><listitem><para>counter.php : serves to identify the users based on the operating system used, the browser, the page of origin, date of the visit...</para></listitem><listitem><para>javascript.php : includes all necessary Javascript (if you need particular Javascript<indexterm><primary>Javascript</primary></indexterm> code, include it in this file, see also <xref linkend="javascript-php">).</para></listitem><listitem><para>meta.php : contains the keywords to pass to the search engines and other parameters of the header.<indexterm><primary>header</primary></indexterm> It is an optimal system for learning how to create keywords and position the site with a good ranking in the search engines.</para></listitem><listitem><para>my_header.php : manages the disclaimer message in the homepage.<indexterm><primary>homepage</primary></indexterm></para></listitem><listitem><para>sql_layer.php : serves to manage the database abstraction layer.<indexterm><primary>layer</primary></indexterm> Transforms SQL instructions to the language of the chosen database.<indexterm><primary>base</primary></indexterm> Remember that <application>PHP-Nuke</application> can manage various databases.<indexterm><primary>databases</primary></indexterm></para></listitem></itemizedlist></listitem></varlistentry><varlistentry><term>db:
</term><listitem><para>Starting from version 6.5, <application>PHP-Nuke</application> uses a new SQL abstraction layer,<indexterm><primary>layer,</primary></indexterm> that of the phpBB forum (see the section &ldquo;Using the SQL Abstraction Layer&rdquo; in the ADDONS-MODULES file that comes with the standard <application>PHP-Nuke</application> package). The layer functions are the same as the ones of sql_layer.<indexterm><primary>layer</primary></indexterm>php, but more extended. Now you can program your modules (<xref linkend="creating-modules">) using either the &ldquo;old&rdquo; sql_layer.<indexterm><primary>layer</primary></indexterm>php (which will continue to be supported in the future for backward compatibility), or the functions found in the files of the DB folder.</para></listitem></varlistentry><varlistentry><term>docs:
</term><listitem><para>Contains this book. Right, this is not only an official HOWTO of the <productname>Linux</productname> Documentation Project, but also the official <application>PHP-Nuke</application> guide!</para></listitem></varlistentry><varlistentry><term>language:
</term><listitem><para>Contains translation files for the basic <application>PHP-Nuke</application> module.<indexterm><primary>module</primary></indexterm> The language file naming convention is lang-english.php.<indexterm><primary>lang-english.php</primary></indexterm> </para><caution>
<title>Attention!</title>
<para>
The translation of the modules must be inserted in the appropriate folders (modules/language) and not appended to these files, as it was done till now.
</para>
</caution>
</listitem></varlistentry><varlistentry><term>Modules:<indexterm><primary>Modules</primary></indexterm>
</term><listitem><para>The modules of <application>PHP-Nuke</application> comprise all the functionality that one can add to it. In the Modules folder we insert the folders of every new module.<indexterm><primary>module</primary></indexterm></para></listitem></varlistentry><varlistentry><term>Themes:<indexterm><primary>Themes</primary></indexterm>
</term><listitem><para>Here we add the graphical interfaces known as &ldquo;Themes<indexterm><primary>Themes</primary></indexterm>&rdquo;, every folder has the name of the corresponding theme and contains a main file called theme.<indexterm><primary>theme</primary></indexterm>php and all other support files.</para></listitem></varlistentry><varlistentry><term>Upgrades:
</term><listitem><para>contains only the files that serve to upgrade the system from a previous version to a newer one (see <xref linkend="upgrade-php-nuke">).</para></listitem></varlistentry></variablelist></sect1>
<sect1 id="main-page-management"><title>Main page management</title><para>The file &ldquo;index.php<indexterm><primary>index.php</primary></indexterm>&rdquo; is very simple one, it has the task to load the main <application>PHP-Nuke</application> page the module that was chosen as the default one to appear in the main page of our site.</para><para>Here in detail is what happens when a client requests the page &ldquo;index.php<indexterm><primary>index.php</primary></indexterm>&rdquo; :</para><itemizedlist><listitem><para>the mainfile.php is included,</para></listitem><listitem><para>a database query is made in order to see which module was set up as the default one,</para></listitem><listitem><para>the origin of the visitor is checked (if he comes from a site that links us, this fact will be inserted in a table in the database).</para></listitem></itemizedlist><para>Various checks are also made and error messages are defined in case the connection to the database fails. This avoids (in part) the error messages from the <acronym>PHP</acronym> preprocessor.<indexterm><primary>preprocessor</primary></indexterm> Even if problems come up, the page will be presented in a standard design<indexterm><primary>sign</primary></indexterm> and the error message will be definable from the inside.</para></sect1>
<sect1 id="module-management"><title>Module management</title><para>For reasons of order, the modules are managed through the files present in the subdirectories that contain them, every module has its own folder in the interior of the folder &ldquo;modules<indexterm><primary>modules</primary></indexterm>&rdquo;.</para><para>In order to be loaded, the module files get included in the modules.php file by passing it the aproppriate parameters. The main page of each module must be called index.php, the other possibly pages possibly present in the module will have an additional variable in the inside of parameter strings by which they are called..</para><para>For example in the AvantGo module (see <xref linkend="frontend">) in order to load the index.<indexterm><primary>index</primary></indexterm>php file, it is enough to pass the module name to the parameter string (by default, the file that will be searched for is index.php):</para><screen><![CDATA[modules.php?name=AvantGo
]]></screen><para>If we instead wanted to call a page other than the default index.php (say, print.php), the string we will have to pass is :</para><screen><![CDATA[modules.php?name=AvantGo&file=print
]]></screen><para>that is the file variable with a value (print) that corresponds to the name of the file we want to load without the .php extension.</para><para>Inside the folder modules/nameofmodule there is also a subfolder called &ldquo;language&rdquo;. In this fashion we manage in a simple and immediate way the multilanguage<indexterm><primary>multilanguage</primary></indexterm> functionality inside the modules.<indexterm><primary>modules</primary></indexterm></para><para>The modules.<indexterm><primary>modules</primary></indexterm>php file works this way:</para><itemizedlist><listitem><para>Includes mainfile.php<indexterm><primary>mainfile.php</primary></indexterm></para></listitem><listitem><para>Verifies whether the module is active or not</para></listitem><listitem><para>Verifies whether the string passes a file name different from index.php<indexterm><primary>index.php</primary></indexterm></para></listitem><listitem><para>Verifies the permissions of the module (whether everybody can see it, or only registered users, or only the administrator).</para></listitem></itemizedlist></sect1>
<sect1 id="admin-management"><title>Administration management </title><variablelist><varlistentry><term>Admin:<indexterm><primary>Admin</primary></indexterm>
</term><listitem><para>contains 4 subfolders (links, language, case, modules) that manage the various administration modules.<indexterm><primary>modules</primary></indexterm> The folder that contains the operating files is admin/modules,<indexterm><primary>modules</primary></indexterm> here we have the files that execute the different admin operations.<indexterm><primary>ations</primary></indexterm></para></listitem></varlistentry></variablelist><para>The folder admin/links<indexterm><primary>admin/links</primary></indexterm> instead says which admin module has to be called and puts a link in the admin area for that module.<indexterm><primary>module</primary></indexterm></para><para>Example (administration module for the FAQ):</para><screen><![CDATA[if (($radminsuper==1) OR ($radminfaq==1)) {
]]><![CDATA[adminmenu("admin.php?op=FaqAdmin ", "" _FAQ." ", "faq.gif");
]]><![CDATA[}
]]></screen><para>This module:<indexterm><primary>module</primary></indexterm></para><itemizedlist><listitem><para>Verifies that administration rights are present (this module may be managed by either the superadmin or an administrator that has been qualified to do so on the FAQ level),</para></listitem><listitem><para>passes a case (op=FaqAdmin) that says to the admin.php file (that includes<indexterm><primary>includes</primary></indexterm> all the admin modules) which module to load,<indexterm><primary>load</primary></indexterm> associates a value in order to translate the term &ldquo;faq<indexterm><primary>faq</primary></indexterm>&rdquo; and associates an icon for the visual administration (faq.gif).</para></listitem></itemizedlist><para>The folder admin/case<indexterm><primary>admin/case</primary></indexterm> instead serves to define which module to use in certain cases. This is important when, using the same admin file, one needs to carry out different operations according to the case passed:</para><screen><![CDATA[Case1 = insert
]]><![CDATA[Case2 = cancel
]]><![CDATA[etc...
]]></screen><para>In fact it says which module to load on verification of a case.<indexterm><primary>case</primary></indexterm> For example, in the module faq the cases are many, let's consider only the last 2:</para><screen><![CDATA[case "FaqAdmin":
]]><![CDATA[case "FaqCatGo":
]]><![CDATA[include ("admin/modules/adminfaq.php");
]]><![CDATA[break;
]]></screen><para>Both cases load the file adminfaq.php but they make it carry out different operations.<indexterm><primary>ations</primary></indexterm> The first one loads the file in the default scheme,<indexterm><primary>scheme</primary></indexterm> the second one instead gives the O.K. for the insertion of a new category.<indexterm><primary>category</primary></indexterm> This happens through a string like</para><screen><![CDATA[admin.php?op=FaqAdmin
]]></screen><para>in the first case and </para><screen><![CDATA[admin.php?op=FaqCatGo
]]></screen><para>in the second.</para></sect1>
</chapter>
<chapter id="session-management"><title>Session management</title><para>I am indepted to Paul S. Owen,<indexterm><primary>Owen</primary></indexterm> Development Team Leader of <ulink url="http://www.phpbb.com">phpBB</ulink>, the standard forum for <application>PHP-Nuke</application> starting from the later 6.x versions, for giving permission to include the following explanation,<indexterm><primary>explanation</primary></indexterm> which can be found in <ulink url="http://www.phpbb.com/phpBB/viewtopic.php?t=69493">http://www.phpbb.com/phpBB/viewtopic.php?t=69493</ulink>, as well as in <ulink url="http://www.phpbb.com/kb/article.php?article_id=54">http://www.phpbb.com/kb/article.php?article_id=54</ulink>:</para><sect1 id="how-sessions-work"><title>How sessions work in the forums</title><para>phpBB uses sessions to &quot;track&quot; users as they move between pages, forums, topics,<indexterm><primary>topics</primary></indexterm> etc. A session is made up of a unique 32 character session_id which identifies the current users. This value is stored in the sessions table and either a temporary (i.e. it's deleted when the browser window is closed) cookie on the users machine or if that doesn't seem to be working it's appended to all URLs.</para><para>The problem with using just a session_id is that it becomes very easy to hijack (takeover) a session.<indexterm><primary>session</primary></indexterm> All a user need do is obtain the session_id and add it to the url as they browse the board.<indexterm><primary>board</primary></indexterm> If the id they grab happens to be a logged in admin or moderator ... well you get the picture.</para><para>What we do to help complicate the situation is also tie the session to the users IP.<indexterm><primary>IP</primary></indexterm> Using this method someone would need to spoof an IP and obtain the session_id<indexterm><primary>session_id</primary></indexterm> in order to hijack a session,<indexterm><primary>session</primary></indexterm> not incredibly difficult but certainly harder ... and with this sort of software it's really a case of making everything harder to do, thus disuading all but the most ardent &quot;hackers&quot;<indexterm><primary>hackers</primary></indexterm> from bothering to attempt anything.</para><para>How do we obtain this IP?<indexterm><primary>IP</primary></indexterm> We check the availability of two variables, REMOTE_ADDR and HTTP_X_FORWARDED_FOR. Firstly we check for HTTP_X_ ..., this is typically set by &quot;nice&quot; proxies,<indexterm><primary>proxies</primary></indexterm> caches, etc. and contains &quot;an&quot; IP which may be the users &quot;real&quot; IP or some other IP.<indexterm><primary>IP</primary></indexterm> If that does not exist or it contains a private or restricted IP range<indexterm><primary>range</primary></indexterm> (several blocks of IPs are reserved by the international bodies responsible for IP allocation) we instead use the value contained in REMOTE_ADDR.<indexterm><primary>REMOTE_ADDR</primary></indexterm> This variable typically contains the users real IP.<indexterm><primary>IP</primary></indexterm></para><para>However, problems arise with how some ISPs operate their systems. Instead of forwarding the users real IP or indeed a different but static IP they simply make available only the IP of the proxy being browsed. The larger ISPs do not use a single proxy or cache,<indexterm><primary>cache</primary></indexterm> the load upon it and data passing through it would be far too great. Instead they use several systems in a &quot;proxy farm&quot; (I tend to refer to it as something containing most of those letters ... ). A user browsing the web may be switched between these machines from one page to another (to help distribute load), with the IP changing as they go.</para><para>Obviously a problem then exists in that phpBB's ability to tie a users session<indexterm><primary>session</primary></indexterm> to a unique id and an IP fails ... because the IP is constantly changing. There are some &quot;nice&quot; ISPs out there that run these farms within a single &quot;class&quot; or block of IPs,<indexterm><primary>IPs</primary></indexterm> e.g. 1.2.3.4,<indexterm><primary>1.2.3.4</primary></indexterm> 1.2.3.5, 1.2.3.6, etc.</para><para>This is why in a previous release of phpBB we introduced a slightly reduced IP checking system which now checks only the first three &quot;quads&quot; of an IP,<indexterm><primary>IP</primary></indexterm> i.e. 1.2.3.4 is checked only for 1.2.3 the 4 is discarded. Remember, that an IPv4 address is 32bits wide, this is generally presented<indexterm><primary>presented</primary></indexterm> in the form of four 8 bit numbers. By checking just the first three numbers (24bits) we neglect 8 bits or 255 (253 in practice) possible IPs ... that's 253 seperate potential proxies ... IOW enough machines for practically any ISP on the planet. However we can go further and reduce that checking to just the first &quot;two quads&quot;, that ignores 255 * 253 IPs!</para><para>The problem is some ISPs don't arrange their IP allocation particularly well, either for historical or other reasons ... AOL is one significant culprit.<indexterm><primary>culprit</primary></indexterm> So what happens is that users can jump between completely different Class A (this is a full 32bit block of IPs) networks, e.g. 100.100.100.100 to 200.100.40.40,<indexterm><primary>200.100.40.40</primary></indexterm> etc. This renders IP validation completely useless for such situations<indexterm><primary>ations</primary></indexterm></para><para>So you ask, &quot;Okay, but why did 2.0.3 not cause all these Invalid_session errors?!&quot;. The answer is fairly simple. When you first visit phpBB (assuming you have autologin enabled) it looks to see if you have a session_id (either in a cookie or the URL). On a new visit you won't have such a session_id and so phpBB creates a new one. If you have autologin set it checks the relevant data and if that matches you are logged in with the appropriate user_id.<indexterm><primary>user_id</primary></indexterm> You can then immediately browse the board,<indexterm><primary>board</primary></indexterm> post messages, do admin tasks (if applicable), etc.</para><para>Now let's take a situation where a naughty person creates a bogus form on their site. You are (for some reason) browsing this form. However, unknown to you this form contains all the necessary data to delete a pile of topics in a given forum (you having moderator rights on a certain board). When you submit that form it will be transmitted to the appropriate website.<indexterm><primary>website</primary></indexterm> No session exists so phpBB,<indexterm><primary>phpBB</primary></indexterm> as noted above creates a new one and immediately processes the form data ... all the relevant topics are deleted from the database and you only find out when the boards &quot;The selected topics have been deleted&quot; message appears ...</para><para>To help negate the effectiveness of this we backported some code from phpBB<indexterm><primary>phpBB</primary></indexterm> 2.2 and introduced additional code. The admin control panel now appends your session_id to every url.<indexterm><primary>url</primary></indexterm> When you browse within that panel it checks the session_id in the url with that stored in the sessions table. If they match, great, if they don't it redirects you back to the ACP index.<indexterm><primary>index</primary></indexterm> This will help prevent users accidently, without their knowledge suffering issues as noted above.</para><para>Similarly the Moderator control panel has the session_id appended to urls and carries out a check. The difference here is that it throws up an Invalid session if the ids do not match, note that redirection like the admin panel wouldn't alter<indexterm><primary>alter</primary></indexterm> the result here ... if you tried submitting data via the MCP with an invalid session you'd just be returned to MCP front page ... losing any data entered previously. Other issues with voting and posting were also addressed thanks to a concerned user notifying us. Thus similar checks were put in place there.</para><para>The problem is that for users whose session is forever being renewed due to their IP changing this extra level of checking can cause issues. For many ISPs the noted changing of 6 to 4 in the IP validation check will be sufficient ... however AOL crops up (as per usual in nearly all similar situations with all software ...) as the sore thumb.<indexterm><primary>thumb</primary></indexterm></para><para>&quot;What can you do about it?&quot; you may ask, very little is the response.<indexterm><primary>response</primary></indexterm> We could remove the extra validation but that leaves a gap that frankly I'm not prepared to leave ... if hadn't addressed this I would make a handsome bet that at some near future point we would've had users shouting and screaming about how damage was done to their boards and why didn't we (phpBB) fix it if we knew about it</para><para>What else can we do? As I said, very little that won't impact users completely unaffected by this issue (of which I'm betting there are a great many) ... in phpBB 2.2 we are introducing a feature to set the level of IP validation<indexterm><primary>validation</primary></indexterm> by the ACP,<indexterm><primary>ACP</primary></indexterm> including disabling it completely. However disabling IP validation will, as noted leave your users open to simplified hijacking.<indexterm><primary>hijacking</primary></indexterm> For many people this may not be a problem and thus could be a solution. To do this in phpBB 2.0 you need to either remove the validation code from sessions.php or change the 6 to a 0 (the relevant lines are as noted in this topic). Be aware of what you are doing though and keep quiet about it ... if people don't know IP validation isn't operational they may believe it still is. If you have security issues you can trace to users sessions being hijacked<indexterm><primary>hijacked</primary></indexterm> we don't want to know about it</para><para>We could introduce a change to sessions whereby what happens when a new session is created is &quot;weakened&quot;. What do I mean by weakened? Well, at present we generate a new session<indexterm><primary>session</primary></indexterm> whenever we cannot validate an existing one. Instead what we could do is compare the users current session_id (if they have one) with that in the database.<indexterm><primary>base</primary></indexterm> If a match is found and the time differential is some &quot;small&quot; number we instead continue that session.<indexterm><primary>session</primary></indexterm> The problem here is that it's just as open to hijacking as removing IP<indexterm><primary>IP</primary></indexterm> validation.<indexterm><primary>validation</primary></indexterm> Why? Because that check will ignore the users IP and care only about the session_id ... and thus isn't something I'm keen on without direct admin control.<indexterm><primary>control</primary></indexterm></para><para>We could, as per a new Mod listed elsewhere on the board, ignore IP validation<indexterm><primary>validation</primary></indexterm> whenever the users IP is within a given list. While this isn't as bad as removing validation completely it's not terribly far off. Why? Because instead of having to go to some trouble to obtain a users current IP you can instead (given you know a user connects via a given ISP or proxy) just look it up ... you still need to spoof it but a step has been removed ... and as noted previously all we can do is make these peoples lives harder. There are additional issues with the extra processing required (which may or may not be significant depending on the number of IPs,<indexterm><primary>IPs</primary></indexterm> users browsing, etc.) and of keeping the list up to date.<indexterm><primary>date</primary></indexterm></para><para>We could append a random set of alphanumerics to every single page, changing the value of it with every page view and storing the new data in the sessions table. This would add protection because a hijacker would need not only the session_id<indexterm><primary>session_id</primary></indexterm> but also the current unique identifier.<indexterm><primary>identifier</primary></indexterm> Of all the ideas this is probably my favourite and may make it into a future release (unless I've missed something obvious which renders it useless or bad for performance!).</para></sect1>
<sect1 id="eliminate-session-checks"><title>How to eliminate session checks</title><para>&quot;Okay, fine but what can we do about it now?!&quot; I hear you say. Well, you can remove or reduce validation as noted above (being aware of what you are doing), you could add the Mod noted above (you'll find it presently in another Invalid session topic ... no doubt it will be moved to one of the Mod forums in time) or finally you could remove the piece of code (from all affected pages) that looks like or similar to this:</para><screen><![CDATA[// session id check
]]><![CDATA[if ($sid == " || $sid != $userdata['session_id'])
]]><![CDATA[{
]]><![CDATA[ message_die(GENERAL_ERROR, 'Invalid_session');
]]><![CDATA[}
]]></screen><para>This removes the added security of validation so if you do this we aren't interested in any security related problems that may arise. I highly recommend that you do not remove the added security from the admin<indexterm><primary>admin</primary></indexterm> control panel.<indexterm><primary>panel</primary></indexterm> Let's clarify a little the modifications that are needed:</para><para>You can either edit line 294 in the includes/session.<indexterm><primary>session</primary></indexterm>php:</para><screen><![CDATA[$ip_check_s = substr($userdata['session_ip'], 0, 6);
]]><![CDATA[$ip_check_u = substr($user_ip, 0, 6);
]]></screen><para>and change the 6 to a 4, or, as a last resort (not endorsed by the phpBB<indexterm><primary>phpBB</primary></indexterm> staff and quite unsafe for the above reasons), you can delete all occurences of the code</para><screen><![CDATA[// session id check
]]><![CDATA[if ($sid == " || $sid != $userdata['session_id'])
]]><![CDATA[{
]]><![CDATA[message_die(GENERAL_ERROR, 'Invalid_session');
]]><![CDATA[}
]]></screen><para>in all files. There are 9 occurences in 6 files:</para><screen><![CDATA[includes/usercp_email.php
]]><![CDATA[includes/usercp_sendpasswd.php
]]><![CDATA[modules/Forums/groupcp.php
]]><![CDATA[modules/Forums/login.php
]]><![CDATA[modules/Forums/modcp.php
]]><![CDATA[modules/Forums/posting.php on line 188
]]></screen><para>But most of the time, just changing the cookie,<indexterm><primary>cookie</primary></indexterm> as described in <xref linkend="invalid-session-in-forums">, will solve the &quot;invalid session&quot; problem.</para></sect1>
</chapter>
<chapter id="editing-PHP-Nuke-files"><title>Editing <acronym>PHP</acronym> (-Nuke) files</title><para>PHP-Nuke files are <acronym>PHP</acronym> files. <acronym>PHP</acronym> files contain plain <acronym>ASCII</acronym> text and as such they can be edited with any decent text editor.<indexterm><primary>editor</primary></indexterm> By &ldquo;decent<indexterm><primary>decent</primary></indexterm>&rdquo; we do not only mean an editor that offers a minimum of comfort in editing texts - most of them do. By &ldquo;decent<indexterm><primary>decent</primary></indexterm>&rdquo; we mean an editor that will not introduce extra (most of the time invisible) characters in your file, that will destroy the rest of your day with PHP<indexterm><primary>PHP</primary></indexterm> (amd PHP-Nuke).</para><para>We wouldn't stress this point if we hadn't seen enough cases of people getting errors from the <acronym>PHP</acronym> interpreter complaining that their config.<indexterm><primary>config</primary></indexterm>php file, for example, contained an error - were no error was visible. For this reason, a warning is in place:</para><warning>
<title>
O quantum est in rebus inane!<footnote><para>How much emptiness there is in things!</para></footnote>
</title>
<para>
Don't even think about editing a <acronym>PHP</acronym> (-Nuke) file with Notepad or Wordpad! You run the risk to introduce invisible characters in your text files, causing spurious errors that will be very hard to find and correct! What may seem to be just blanks or empty space, is going to drive you insane!
</para>
</warning>
<para>So, if you are not supposed to use Notepad or Wordpad, what are the alternatives<indexterm><primary>alternatives</primary></indexterm>? What decent text editors are out there for editing our <acronym>PHP</acronym> and <application>PHP-Nuke</application> files? In the following sections, we will present a few of them. See also <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=122">Decent Text Editor</ulink>.</para><sect1 id="vi"><title>vi</title><para>FIXME<indexterm><primary>FIXME</primary></indexterm></para></sect1>
<sect1 id="Emacs"><title>Emacs</title><para>FIXME<indexterm><primary>FIXME</primary></indexterm></para></sect1>
<sect1 id="Bluefish"><title>Bluefish</title><para>FIXME<indexterm><primary>FIXME</primary></indexterm></para></sect1>
<sect1 id="UltraEdit"><title>UltraEdit</title><para>FIXME<indexterm><primary>FIXME</primary></indexterm></para></sect1>
<sect1 id="WinSyntax"><title>WinSyntax</title><para>FIXME<indexterm><primary>FIXME</primary></indexterm></para></sect1>
<sect1 id="HTMLKit"><title>HTMLKit</title><para>FIXME<indexterm><primary>FIXME</primary></indexterm></para></sect1>
<sect1 id="Crimson-Editor"><title>Crimson Editor</title><para>FIXME<indexterm><primary>FIXME</primary></indexterm></para></sect1>
<sect1 id="PHPEd"><title>PHPEd</title><para>FIXME<indexterm><primary>FIXME</primary></indexterm></para></sect1>
</chapter>
<chapter id="modifying-PHP-Nuke-database"><title>Modifying the <application>PHP-Nuke</application> database</title><sect1 id="user-extra-information"><title>More than 255 characters of user extra information</title><para>By clicking on the icon with the title &ldquo;Your Info&rdquo; in the user account menu (see <xref linkend="frontend">), you arrive at a HTML form where you can enter various pieces of information<indexterm><primary>information</primary></indexterm> about yourself, in addition to your personal preferences.<indexterm><primary>preferences</primary></indexterm> One of the fields, the &ldquo;Extra Info&rdquo; field, gives you the opportunity to tell something about yourself that other visitors can read when they click on your profile.<indexterm><primary>profile</primary></indexterm> However, you will not be able to enter more than 255 characters of extra information.<indexterm><primary>information</primary></indexterm> That's a bit too few, even for moderately turbulent biographies. To change that, you must find out where that information is stored in the database.<indexterm><primary>base</primary></indexterm></para><para>
<figure id="fig-extra-info">
<title>
Extra Info field of User Personal Information (Your Info)
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1128;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1128;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1128;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1128;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Extra Info field of User Personal Information (Your Info)</phrase>
</textobject>
<caption>
<para>Extra Info field of User Personal Information (Your Info)</para>
</caption>
</mediaobject>
</figure>
</para><para>That extra information is stored in the field &quot;bio&quot; of the nuke_users table (assuming the table prefix,<indexterm><primary>prefix</primary></indexterm> $prefix,<indexterm><primary>prefix</primary></indexterm> is &quot;nuke&quot; for you, see <xref linkend="config-php-file">). Thus, what you have to do is log in your database and change the length of the bio field. Currently, it is defined as &quot;tinytext&quot;<indexterm><primary>tinytext</primary></indexterm> which gives the limitation of 255 characters (see <ulink url="http://www.mysql.com/doc/en/String_types.html">MySQL String Types</ulink>).</para><para>Once logged in the MySQL database,<indexterm><primary>base</primary></indexterm> do on the MySQL prompt<footnote><para>See <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=12907">edit module your_acount</ulink>.</para></footnote>:</para><screen><![CDATA[alter table nuke_users modify bio text;
]]></screen><para>This will give you the next possible (see <ulink url="http://www.mysql.com/doc/en/Storage_requirements.html">MySQL Column Type Storage Requirements</ulink>) maximum length of 2^16-2. That's a little less than 65KB of text. That should be enough text for your visitors to write a small story of their life. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
</sect1>
</chapter>
<chapter id="modifying-PHP-Nuke-texts"><title>Modifying <application>PHP-Nuke</application> texts</title><para>All texts that appear in <application>PHP-Nuke</application> are strings defined in so-called language files - and are thus fully customizable to your needs:</para><sect1 id="General-PHP-Nuke-texts"><title>General <application>PHP-Nuke</application> texts</title><para>General texts are stored in the files under the language folder. The naming of those language files follows the convention &ldquo;lang-languagename.php<indexterm><primary>lang-languagename.php</primary></indexterm>&rdquo;. Thus, english texts are held in language/lang-english.php,<indexterm><primary>lang-english.php</primary></indexterm> chinese ones in language/lang-chinese.<indexterm><primary>chinese</primary></indexterm>php etc. All you have to do to change a text, is edit the aproppriate file for your language with a <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=122">decent text editor</ulink> (see also <xref linkend="editing-PHP-Nuke-files">). </para><para>For example, to change the text that is displayed besides the Search button (&ldquo;Search&rdquo; for the english language), open language/lang-english.php with a <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=122">decent text editor</ulink> and find the line that contains the text:</para><screen><![CDATA[define("_SEARCH","Search");
]]></screen><para>This is a <acronym>PHP</acronym> instruction that tells the <acronym>PHP</acronym> interpreter to define the constant _SEARCH as the text string &ldquo;Search&rdquo;. Thus, whatever you put in the text string will be the content of the _SEARCH<indexterm><primary>_SEARCH</primary></indexterm> constant. The developers (at least in an ideal world) will only use constants (and database-driven,<indexterm><primary>database-driven</primary></indexterm> dynamic information) for their texts, so that you only need to do your changes at one place to be valid everywhere. To change the search text to &ldquo;Search my homepage<indexterm><primary>homepage</primary></indexterm>&rdquo;, you thus need to change the above line to</para><screen><![CDATA[define("_SEARCH","Search my homepage");
]]></screen><para>It is in this manner that internationalization of <application>PHP-Nuke</application> takes place, by the way. People who want to translate <application>PHP-Nuke</application> to their language, get a fresh copy<indexterm><primary>copy</primary></indexterm> of language/lang-english.php and start translating the text strings in the &ldquo;define&rdquo; directives,<indexterm><primary>directives</primary></indexterm> then send the lang-newlanguage.php file to <ulink url="http://phpnuke.org">phpnuke.org</ulink> for inclusion in the next release.</para><tip>
<title>
HTML code in text constants
</title>
<para>
You are not confined to text, when you change the texts in PHP-Nuke's language files. This may sound paradoxical, but if you think that the language files are just usual <acronym>PHP</acronym> files that define some constants, then you will see that nothing really prevents you from &ldquo;abusing&rdquo; their purpose and mixing them with...HTML code, for example. <inlinemediaobject> <![ %output.print.png; [ <imageobject><imagedata fileref="./images/icon_eek.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject><imagedata fileref="icon_eek.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject><imagedata fileref="./images/icon_eek.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject><imagedata fileref="icon_eek.bmp" format="BMP"> </imageobject> ]]> <textobject><phrase>eek!</phrase> </textobject></inlinemediaobject>
</para>
<para>
Thus it is perfectly legal to change:
</para>
<screen>
<![CDATA[define("_WRITES","writes"); ]]>
</screen>
<para>to:</para>
<screen>
<![CDATA[define("_WRITES","&nbsp;writes"); ]]>
</screen>
<para>
In this case, we entered a non-breaking space before the translation of the _WRITES constant. This is because we noticed that a space was missing before the "writes" in the &ldquo;user writes&rdquo; string that is printed next to an article in the news. Instead of correcting the code in the News module, we opted for the quick'n dirty way. It's not recommended, because it mangles user-supplied data with code - but it is nonetheless possible, see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=17878">Posting Articles or Story</ulink>.
</para>
</tip>
</sect1>
<sect1 id="PHP-Nuke-module-texts"><title>PHP-Nuke module texts</title><para>PHP-Nuke module texts are also customizable,<indexterm><primary>customizable</primary></indexterm> but are stored in separate folders: each module comes with a language folder containing a lang-xxx.php<indexterm><primary>lang-xxx.php</primary></indexterm> file with the translation strings for the text constants that are relevant to only that module.<indexterm><primary>module</primary></indexterm> For example, the Forums module contains a language folder, stored as modules/Forums/language, the Your_Account module (which handles user logins, registration,<indexterm><primary>registration</primary></indexterm> authentication and management of the users' info,<indexterm><primary>info</primary></indexterm> mail, messages and personal settings) comes with a language folder stored as modules/Your_Account/language etc.</para><para>To change a module specific text, edit the appropriate language file lang-xxx.php<indexterm><primary>lang-xxx.php</primary></indexterm>, exactly as described in <xref linkend="General-PHP-Nuke-texts"> for general <application>PHP-Nuke</application> texts. For example, to customize the email text sent to a new user after registration,<indexterm><primary>registration</primary></indexterm> open the file /modules/Your_Account/language/lang-english.php in a <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=122">decent text editor</ulink>, find the lines</para><screen><![CDATA[define("_YOUUSEDEMAIL","You or someone else has used your email account");
]]><![CDATA[define("_TOREGISTER","to register an account at");
]]></screen><para>and change them to something more sophisticated,<indexterm><primary>sophisticated</primary></indexterm> like</para><screen><![CDATA[define("_YOUUSEDEMAIL","Nil sine magno vita labore dedit mortalibus!]]><footnote><para>Life has given nothing to mortals without hard work!</para></footnote><![CDATA[");
]]><![CDATA[define("_TOREGISTER","Please register your account at");
]]></screen></sect1>
<sect1 id="PHP-Nuke-module-and-block-titles"><title>PHP-Nuke module and block titles</title><para>You can change a module's or block's title from the module or block administration panel respectively: for a module or active block,<indexterm><primary>block</primary></indexterm> click on the Edit link on the line for that module/block,<indexterm><primary>block</primary></indexterm> change and save. The text you enter in the &ldquo;Title<indexterm><primary>Title</primary></indexterm>&rdquo; field will be the new title to be displayed.</para></sect1>
</chapter>
<chapter id="customization"><title>Customising <application>PHP-Nuke</application> themes </title><para>In this chapter we will talk about themes in <application>PHP-Nuke</application>. We will discuss the following topics:<indexterm><primary>topics</primary></indexterm></para><itemizedlist><listitem><para>Structure of a <application>PHP-Nuke</application> theme (<xref linkend="topic-structure">),</para></listitem><listitem><para>Modifying the <application>PHP-Nuke</application> theme HTML template (<xref linkend="template">),</para></listitem><listitem><para>Modifying the <application>PHP-Nuke</application> theme header (<xref linkend="php-nuke-theme-modifying-header">),</para></listitem><listitem><para>Modifying the <application>PHP-Nuke</application> theme body (<xref linkend="php-nuke-theme-modifying-body">),</para></listitem><listitem><para>Modifying the <application>PHP-Nuke</application> theme index (<xref linkend="php-nuke-theme-modifying-index">),</para></listitem><listitem><para>Modifying the <application>PHP-Nuke</application> theme footer (<xref linkend="php-nuke-theme-modifying-footer">),</para></listitem><listitem><para>Modifying the <application>PHP-Nuke</application> theme icons (<xref linkend="php-nuke-theme-modifying-icons">),</para></listitem><listitem><para>PHP-Nuke theme rules (<xref linkend="theme-rules">),</para></listitem><listitem><para>How to change a buggy <application>PHP-Nuke</application> theme (<xref linkend="change-buggy-php-nuke-theme">),</para></listitem><listitem><para>How to prevent users from changing the theme in <application>PHP-Nuke</application> (<xref linkend="prevent-users-from-changing-php-nuke-theme">),</para></listitem><listitem><para>How to change the <application>PHP-Nuke</application> theme depending on module (<xref linkend="change-php-nuke-theme-depending-on-module">),</para></listitem><listitem><para>How to change font size in <application>PHP-Nuke</application> (<xref linkend="change-font-size-php-nuke">).</para></listitem></itemizedlist><sect1 id="topic-structure"><title>Structure of a <application>PHP-Nuke</application> theme</title><para>Making your own personal graphical theme for your site is very important so that you don't have another <application>PHP-Nuke</application> clone, if your site looks the same as other sites it dosn't make you, the Webmaster look very professional. Personalising the portal starts from the graphical side of things. Knowing how to put your hands on a <application>PHP-Nuke</application> theme means being able to play with all of the graphical elements that we can use. The example theme we will use in this chapter is the NukeNews theme,<indexterm><primary>theme</primary></indexterm> made by Francisco Burzi for <application>PHP-Nuke</application>. It's a theme composed of a lot of HTML files, all included in theme.<indexterm><primary>theme</primary></indexterm>php. This is a very good solution that permits you to manage the graphical part of the theme through an editor like DreamWeaver using the least amount of <acronym>PHP</acronym> code.</para><para>For a graphical anatomy of a <application>PHP-Nuke</application> theme,<indexterm><primary>theme</primary></indexterm> please have a look at the <ulink url="theme.html">theme.html</ulink> file. As you can see, each <application>PHP-Nuke</application> page follows the classic 3-column table layout:<indexterm><primary>layout</primary></indexterm> in the left and right columns you can position small blocks, while in the center, wider column, you should position the larger blocks. It is also the center column where the currently viewed module is shown.</para><para>The NukeNews theme,<indexterm><primary>theme</primary></indexterm> for example, is structured in the following way (<xref linkend="fig-theme-structure-nukenews">):</para><itemizedlist><listitem><para>theme.php: controls the main functions of the variables for the background<indexterm><primary>background</primary></indexterm> colors.</para></listitem><listitem><para>tables.php: controls the functions opentable() and closetable().</para></listitem><listitem><para>header.html: controls the header for your site.</para></listitem><listitem><para>footer.html: controls the footer for your site.</para></listitem><listitem><para>blocks.html: controls the blocks.</para></listitem><listitem><para>center_right.html: controls the layout of the page.</para></listitem><listitem><para>center_left.html: controls the layout of the page.</para></listitem><listitem><para>story_home.html: controls the layout of the page.</para></listitem><listitem><para>story_page.html: controls the layout of the page.</para></listitem></itemizedlist><para>
<figure id="fig-theme-structure-nukenews">
<title>
Structure of the NukeNews theme.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1129;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1129;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1129;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1129;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Structure of the NukeNews theme.</phrase>
</textobject>
<caption>
<para>Structure of the NukeNews theme.</para>
</caption>
</mediaobject>
</figure>
</para><para>These files are included in the functions specified in theme.php We then have a style sheet (<xref linkend="CSS-syntax">), called style.css (style/style.css), included in the header.html file in our theme folder. For convention, the style sheet must always be called style.css and must always be contained in one folder called &quot;style&quot; inside of our theme folder. The images generally are grouped in a folder called &quot;images&quot;<indexterm><primary>images</primary></indexterm> that is always found in our themes folder. </para><para>The folder structure of the NukeNews theme will be : </para><itemizedlist><listitem><para>themes/NukeNews<indexterm><primary>themes/NukeNews</primary></indexterm></para></listitem><listitem><para>themes/NukeNews/style/</para></listitem><listitem><para>themes/NukeNews/images/</para></listitem></itemizedlist><para>Always remember that case is important, you must respect the difference between UPPERCASE and lowercase for compatibility with any Unix systems. </para><para>The theme.php file is the heart of all PHP-Nuke's graphical management.<indexterm><primary>management</primary></indexterm> The theme.php is the file that creates the managing functions of all of PHP-Nuke's components (header,<indexterm><primary>header</primary></indexterm> footer, central parts, block...).</para><para>The technique of putting HTML code in separate files, that are then included in theme.<indexterm><primary>theme</primary></indexterm>php, is not used in all themes (see <xref linkend="fig-theme-structure-other">). Some programmers include all the HTML in the theme.php file. However, including it separately solves many problems such as HTML formatting, that would otherwise be included in the <acronym>PHP</acronym> code. It also gives us the possibility of editing all with a visual editor (WYSIWYG). </para><para>
<figure id="fig-theme-structure-other">
<title>
Structure of other themes, without HTML templates.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1130;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1130;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1130;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1130;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Structure of other themes, without HTML templates.</phrase>
</textobject>
<caption>
<para>Structure of other themes, without HTML templates.</para>
</caption>
</mediaobject>
</figure>
</para><para>The themeheader() function manages the site header.<indexterm><primary>header</primary></indexterm> It is composed of various tables that form the heading, and sometimes also defines some elements of the body tag that are not included in the style sheet and the variables that are placed inside the included html files. </para><variablelist><varlistentry><term>Example:
</term><listitem><para>The variable $theuser is defined inside of the themeheader() function<indexterm><primary>function</primary></indexterm> and is then shown in the header.<indexterm><primary>header</primary></indexterm>html file in a table: </para></listitem></varlistentry></variablelist><para>Code in theme.<indexterm><primary>theme</primary></indexterm>php (that defines the $theuser variable)</para><screen><![CDATA[if ($username == "Anonymous") {
]]><![CDATA[ $theuser = "&nbsp;&nbsp; <a href=\"modules.php
]]><![CDATA[ ?name=Your_Account &op=new_user\">Create an account";
]]><![CDATA[} else {
]]><![CDATA[ $theuser = "&nbsp;&nbsp;Welcome $username!";
]]><![CDATA[}
]]></screen><para>Code in header.html (that displays the $theuser variable)</para><screen><![CDATA[<td width="15% "nowrap >< font class="content" color="#363636 " >
]]><![CDATA[<b> $theuser </b></font></td>
]]></screen><para>It is also in the themeheader() function that the position of the advertisement banners is hardcoded.<indexterm><primary>hardcoded</primary></indexterm> If you are not satisfied with the placement of your banners,<indexterm><primary>banners</primary></indexterm> look for the lines</para><screen><![CDATA[if ($banners == 1) {
]]><![CDATA[ include("banners.php");
]]><![CDATA[}
]]></screen><para>These lines are responsible for the output of the banner.<indexterm><primary>banner</primary></indexterm> By changing their place in the <acronym>PHP</acronym> code, you can achieve a different banner<indexterm><primary>banner</primary></indexterm> placement.</para><para>The themefooter(); function is responsible for the footer of our site.</para><para>It has some interesting elements we have to analyse:<indexterm><primary>analyse</primary></indexterm></para><para>First of all, it identifies if the displayed page has got the $index variable set equal to 1, in this case we will also insert the right blocks on our page, but if instead $index==0 then the right blocks will not appear on our page. </para><para>It then defines the footer messages (which are captured from config.php) and inserts all them in a variable that is recalled from the footer.html file. </para><para>The function themeindex() manages the news in Home Page and formats them adding elements according to various cases using the function &quot;if&quot;. It also includes the story_home.htm file.</para><para>The function themearticle() instead manages the internal news page (that we can see by pushing on &quot;Read more...&quot;; remember that the layout part in this case is achieved by including the story_page.htm file, but the blocks that must be included (i.e. the article's survey,<indexterm><primary>survey</primary></indexterm> correlated links etc.) are defined by the news module. </para><para>The function themesidebox() instead manages the layout of the box that we create or that we find already made (see <xref linkend="blocks">), it too includes a file called blocks.htm that defines the style and the layout.<indexterm><primary>layout</primary></indexterm> </para><para>We have ignored an element of the file theme.php. These are the variables that format the text, some of them are inserted in css (the style sheet) but others are instead defined at the beginning of the theme.php file. </para><para>Let's see the variables from the NukeNews theme:<indexterm><primary>theme</primary></indexterm> </para><screen><![CDATA[$bgcolor1 = "# efefef";
]]><![CDATA[$bgcolor2 = "# cfcfbb";
]]><![CDATA[$bgcolor3 = "# efefef";
]]><![CDATA[$bgcolor4 = "# cfcfbb";
]]><![CDATA[$textcolor1 = "# 000000";
]]><![CDATA[$textcolor2 = "# 000000";
]]></screen><para>As you see the expression values of these variables are in decimal format.<indexterm><primary>format</primary></indexterm> </para><para>Define your site colours - $bgcolor2 is generally used for table edges as you can see in the function opentable(), $bgcolor1 is used for table background.<indexterm><primary>background</primary></indexterm> The others two background variables use the same criteria.<indexterm><primary>criteria</primary></indexterm> $textcolor1 and $textcolor2 are used to format the text colour.<indexterm><primary>colour</primary></indexterm> </para><para>Now we have to examine what is included in the tables.php file. This file creates 4 functions (opentable(); closetable(); opentable2(); closetable2();) that include HTML tags that open and close tables in a predefined way.</para><para>It is very easy to use when creating modules (see <xref linkend="creating-modules">) , you don't have to rewrite the HTML every time you want to create a table but it's enough with the following syntax:<indexterm><primary>syntax</primary></indexterm></para><screen><![CDATA[opentable();
]]><![CDATA[echo "Content of the table";
]]><![CDATA[closetable();
]]></screen><para>In this way you've created a table in a fast and effective way. But how is this function structured? We will examine first opentable(); then closetable();</para><note>
<title>Please note</title>
<para>
These are php functions so you have to respect the HTML syntax inside php adding \ before every " (ie align="left" must be written as align=\"left\")
</para>
</note>
<screen><![CDATA[function OpenTable() {
]]><![CDATA[global $bgcolor1, $bgcolor2;
]]><![CDATA[echo "<table width=\"100% \" border=\"0 \ "cellspacing=\"1 \" cellpadding=\"0 \ "bgcolor=\"$bgcolor2 \" >< tr >< td > \n ";
]]><![CDATA[echo "< table width=\"100% \" border=\"0 \ "cellspacing=\"1 \" cellpadding=\"8 \ "bgcolor=\"$bgcolor1 \" >< tr >< td > \n ";
]]><![CDATA[}
]]></screen><para>The syntax is very simple, isn't it? </para><itemizedlist><listitem><para>The function is opened</para></listitem><listitem><para>Necessary variables are called ($bgcolor1, $bgcolor2) </para></listitem><listitem><para>We open a table 100% wide and we define the background colours for it</para></listitem><listitem><para>Open Line, Open Column</para></listitem><listitem><para>We insert a new table 100% wide (for the edges) </para></listitem><listitem><para>The width and height characteristics are defined.</para></listitem><listitem><para>line column</para></listitem></itemizedlist><para>We stop on the column because it's here we will insert the table content (In fact opentable is where we start from to close this table!)</para><screen><![CDATA[function CloseTable() {
]]><![CDATA[echo "</td ></tr ></table ></td ></tr ></table > \n";
]]><![CDATA[}
]]></screen><para>In fact...</para><itemizedlist><listitem><para>The function is opened</para></listitem><listitem><para>You close the Column; You close the Line</para></listitem><listitem><para>You close the Inner Table</para></listitem><listitem><para>You close the Column; You close the Line</para></listitem><listitem><para>You close the Outer Table</para></listitem></itemizedlist><para>Its easy to construct HTML functions with PHP,<indexterm><primary>PHP</primary></indexterm> isnt it?</para></sect1>
<sect1 id="template"><title>Modifying the <application>PHP-Nuke</application> theme HTML template</title><para>In this section we will see how to modify the HTML template that is used by the <application>PHP-Nuke</application> themes to display our page. Topics covered are:</para><itemizedlist><listitem><para>Example creation of HTML file to include in the theme (<xref linkend="example-creation-HTML-template">).</para></listitem></itemizedlist><sect2 id="example-creation-HTML-template"><title>Example creation of HTML file to include in the theme</title><para>We will not analyse the HTML syntax of all the files, we think it's better that you understand the principles that are used and that you learn a few tricks that allow you to use a visual editor such as DreamWeaver.<indexterm><primary>DreamWeaver</primary></indexterm> </para><variablelist><varlistentry><term>Example:
</term><listitem><para>The block is created in this way: </para><screen><![CDATA[<table border="0 "cellpadding="1" cellspacing="0
]]><![CDATA["bgcolor="#000000" width="150 "><tr><td>
]]><![CDATA[<table border="0 "cellpadding="3" cellspacing="0
]]><![CDATA["bgcolor="#dedebb" width="100% "><tr>< td align="left" >
]]><![CDATA[<font class="content "color="#363636" ><b> $$title </b ></font>
]]><![CDATA[</td></tr></table></td></tr></table>
]]><![CDATA[<table border="0 "cellpadding="0" cellspacing="0
]]><![CDATA["bgcolor="#ffffff" width="150 " >
]]><![CDATA[<tr valign="top "><td bgcolor="#ffffff">
]]><![CDATA[$content
]]><![CDATA[</td></tr></table>
]]><![CDATA[< br >
]]></screen></listitem></varlistentry></variablelist><para>As you see, we create a table of fixed width (in our case 150) and we assign<indexterm><primary>sign</primary></indexterm> it some colours (for the background etc...). We also assign two variables ($title and $content) that will, once included in theme.php, load the title and the content of the block.<indexterm><primary>block</primary></indexterm> It would have been useful, for a code clarity reasons, to define background<indexterm><primary>background</primary></indexterm> values in the CSS tables instead.</para><para>To have all the necessary cases to get the conclusions of this chapter and to write a pair of rules,<indexterm><primary>rules</primary></indexterm> we have to analyse a very simple module that includes a case we have still not mentioned, the images management:<indexterm><primary>management</primary></indexterm></para><screen><![CDATA[</td><td><img src="themes/NukeNews/images/pixel.gif
]]><![CDATA["width="15" height="1 "border="0" stop = "">
]]><![CDATA[</td><td valign="top" width="100%">
]]></screen><para>The image is a spacer that adds a space of 15 pixels,<indexterm><primary>pixels</primary></indexterm> but where do we load the image from? Which path do we have to assign it? Remember that the theme.php file is included in the <application>PHP-Nuke</application> root directory , so the image path must start from root to the indicated theme.<indexterm><primary>theme</primary></indexterm> The path to the image &quot;pixel.gif&quot; is &quot;themes/NukeNews/images/pixel.gif&quot; </para><caution>
<title>Attention!</title>
<para>
When you add images in an automatic way by using a visual editor, the path will be only images/image.gif, and you will have to correct it by hand, adding the correct path.
</para>
</caution>
<para>Another trick is to assign, in theme.php, a variable to the name of the theme,<indexterm><primary>theme</primary></indexterm> to make it independent from possible changes of the folder name. So for the variable $nameoftheme = &quot; NukeNews &quot;, the syntax of the image path will be: </para><screen><![CDATA[<img src="themes/$nameoftheme/images/pixel.gif">
]]></screen></sect2>
</sect1>
<sect1 id="php-nuke-theme-modifying-header"><title>Modifying the <application>PHP-Nuke</application> theme header</title><para>The theme header is constructed in the function themeheader() of the theme<indexterm><primary>theme</primary></indexterm> in question. You will find this function in the file theme.<indexterm><primary>theme</primary></indexterm>php, in the folder themes/YourTheme (where YourTheme is the name of your theme,<indexterm><primary>theme</primary></indexterm> e.g. themes/NukeNews). </para><itemizedlist><listitem><para><xref linkend="PHP-Nuke-header-create-top-navigation-bar"></para></listitem><listitem><para><xref linkend="PHP-Nuke-header-insert-SlashOcean-search-box"></para></listitem><listitem><para><xref linkend="PHP-Nuke-header-change"></para></listitem><listitem><para><xref linkend="PHP-Nuke-header-change-logo"></para></listitem><listitem><para><xref linkend="PHP-Nuke-header-change-logo-dynamic"></para></listitem><listitem><para><xref linkend="PHP-Nuke-header-change-banner-placement"></para></listitem><listitem><para><xref linkend="PHP-Nuke-header-watermark-background-image"></para></listitem><listitem><para><xref linkend="PHP-Nuke-header-display-flash-object"></para></listitem><listitem><para><xref linkend="hide-left-blocks"></para></listitem></itemizedlist><sect2 id="PHP-Nuke-header-create-top-navigation-bar"><title>How to create a top navigation bar as in NukeNews theme</title><para>
<figure id="fig-top-nav-bar">
<title>
Top navigation bar in the NukeNews theme.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1131;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1131;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1131;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1131;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Top navigation bar in the NukeNews theme.</phrase>
</textobject>
<caption>
<para>Top navigation bar in the NukeNews theme.</para>
</caption>
</mediaobject>
</figure>
</para><para>Sometimes, like in the case of the NukeNews theme,<indexterm><primary>theme</primary></indexterm> the themeheader() function will include the contents of a separate file, written in pure HTML:<indexterm><primary>HTML</primary></indexterm></para><screen><![CDATA[ $tmpl_file = "themes/NukeNews/header.html";
]]><![CDATA[ $thefile = implode("", file($tmpl_file));
]]><![CDATA[ $thefile = addslashes($thefile);
]]><![CDATA[ $thefile = "\$r_file=\"".$thefile."\";";
]]><![CDATA[ eval($thefile);
]]><![CDATA[ print $r_file;
]]></screen><para>The header.<indexterm><primary>header</primary></indexterm>html file, which is &quot;evaluated&quot; here, contains HTML code that creates the &quot;top navigation bar&quot;, the one with the &quot;Home&quot;, &quot;Topics&quot;, &quot;Downloads<indexterm><primary>ads</primary></indexterm>&quot;, &quot;Your Account&quot;<indexterm><primary>Your Account</primary></indexterm> etc. links (<xref linkend="fig-top-nav-bar">):</para><screen><![CDATA[<tr valign="middle" bgcolor="#dedebb">
]]><![CDATA[<td width="15%" nowrap><font class="content" color="#363636">
]]><![CDATA[<b>$theuser</b></font></td>
]]><![CDATA[<td align="center" height="20" width="70%"><font class="content"><B>
]]><![CDATA[<A href="index.php">Home</a>
]]><![CDATA[<5B>
]]><![CDATA[<A href="modules.php?name=Topics">Topics</a>
]]><![CDATA[<5B>
]]><![CDATA[<A href="modules.php?name=Downloads">Downloads</a>
]]><![CDATA[<5B>
]]><![CDATA[<A href="modules.php?name=Your_Account">Your Account</a>
]]><![CDATA[<5B>
]]><![CDATA[<A href="modules.php?name=Submit_News">Submit News</a>
]]><![CDATA[<5B>
]]><![CDATA[<A href="modules.php?name=Top">Top 10</a>
]]><![CDATA[</B></font>
]]><![CDATA[</td>
]]><![CDATA[<td align="right" width="15%"><font class="content"><b>
]]><![CDATA[<script type="text/javascript">
]]><![CDATA[<!-- // Array ofmonth Names
]]><![CDATA[var monthNames = new Array(
]]><![CDATA["January","February","March","April","May","June","July","August","September",
]]><![CDATA["October","November","December");
]]><![CDATA[var now = new Date();
]]><![CDATA[thisYear = now.getYear();
]]><![CDATA[if(thisYear < 1900) {thisYear += 1900}; // corrections if Y2K display problem
]]><![CDATA[document.write(monthNames[now.getMonth()] + " " + now.getDate() + ", " + thisYear);
]]><![CDATA[// -->
]]><![CDATA[</script></b></font></td>
]]><![CDATA[<td> </td>
]]><![CDATA[</tr>
]]></screen><para>Thus, if you want to delete or change this top navigation bar, you will have to delete or change the above code to reflect your needs (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=72">How to change the top menu (top navigation bar) of PHP-Nuke</ulink> and <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=268">how to remove the search box from the top menu of PHP-Nuke</ulink>). A similar technique is used in the Odyssey theme,<indexterm><primary>theme</primary></indexterm> where one uses the contents of themes/Odyssey/left_center.html, additionally to themes/Odyssey/header.<indexterm><primary>header</primary></indexterm>html.</para></sect2>
<sect2 id="PHP-Nuke-header-insert-SlashOcean-search-box"><title>How to insert a Search Box as in SlashOcean theme</title><para>The SlashOcean theme contains a Welcome message and a Search box in its header,<indexterm><primary>header</primary></indexterm> as a close inspection of the code in the themeheader() function of themes/SlashOcean/theme.<indexterm><primary>theme</primary></indexterm>php reveals:</para><screen><![CDATA[echo "<br>
]]><![CDATA[<center>
]]><![CDATA[<table cellpadding=0 cellspacing=0 border=0 width=99% align=center><tr><td align=left>
]]><![CDATA[<a href=$nukeurl><img src=themes/SlashOcean/images/logo.gif Alt=\"Welcome to $sitename\"
]]><![CDATA[border=0></a>
]]><![CDATA[</td><td align=right width=100%>
]]><![CDATA[ <form action=modules.php?name=Search&amp;method=post>
]]><![CDATA[ <font class=content><input type=text name=query width=20 size=20 length=20>
]]><![CDATA[ </td>
]]><![CDATA[ <td align=right>&nbsp;&nbsp;<input type=submit value=\""._SEARCH."\"></td>
]]><![CDATA[ </form>";
]]><![CDATA[ echo "</td></tr></table><br>";
]]></screen><para>You can use this code if you wish to have a search box besides your logo,<indexterm><primary>logo</primary></indexterm> as in SlashOcean.<indexterm><primary>SlashOcean</primary></indexterm> You will find similar constructs in the other themes,<indexterm><primary>themes</primary></indexterm> e.g. Kaput or Slash.<indexterm><primary>Slash</primary></indexterm> </para></sect2>
<sect2 id="PHP-Nuke-header-change"><title>How to change the <application>PHP-Nuke</application> header depending on some global feature</title><para>In some cases you may need to change the <application>PHP-Nuke</application> header according to some globally available information about the current user. For example, you may want to display a menu that is differently structured if the user's language is, say, french,<indexterm><primary>french</primary></indexterm> leaving the standard menu structure untouched otherwise.</para><para>The key to such changes is always to declare the globally available feature as being &ldquo;global<indexterm><primary>global</primary></indexterm>&rdquo; in the themeheader() function in theme.<indexterm><primary>theme</primary></indexterm>php. Then you can use its value for a simple check that will echo the right HTML incantations if the check succeeds. Let's take for example the above case,<indexterm><primary>case</primary></indexterm> where the globally available feature is nothing else but the current language setting:</para><screen><![CDATA[global $currentlang;
]]><![CDATA[if ($currentlang == "french") {
]]><![CDATA[ echo "<a href=\"/special/link/to/my/services/for/french/users\"><b>"
]]><![CDATA[ ._MESSERVICES."</b></A>\n";
]]><![CDATA[}
]]><![CDATA[else if ($currentlang == "english") {
]]><![CDATA[ echo "<a href=\"/some/default/link/for/other/users\">"
]]><![CDATA[ ._DEFAULTLINK."</a>\n";
]]><![CDATA[}
]]></screen><para>This code, put in the themeheader() function of theme.<indexterm><primary>theme</primary></indexterm>php in the aproppriate place (depending on where exacly you want it to appear), will display a special menu link if the user's language is french.<indexterm><primary>french</primary></indexterm> Instead of the current language, any user setting that is globally available can be used. The only work you have to do is to find out which variable stores the global<indexterm><primary>global</primary></indexterm> setting you need ($currentlang in the above example).</para><para>User information is stored in the userinfo array. This array is filled with a call to the getusrinfo() function.<indexterm><primary>function</primary></indexterm> Thus a simple way to arrive at some information that is special to the currently logged-in user, is to write somethink like</para><screen><![CDATA[ global $user, $userinfo;
]]><![CDATA[ if(is_user($user)) {
]]><![CDATA[ getusrinfo($user);
]]><![CDATA[ }
]]></screen><para>You have then some user-specific settings at your disposal:<indexterm><primary>disposal</primary></indexterm></para><screen><![CDATA[$name = $userinfo['uname'];
]]><![CDATA[$uid = $userinfo['uid'];
]]><![CDATA[$email_real = $userinfo['email'];
]]><![CDATA[$email_fake = $userinfo['femail'];
]]><![CDATA[$url = $userinfo['url'];
]]><![CDATA[$avatar = $userinfo['user_avatar'];
]]><![CDATA[$newsletter = $userinfo['newsletter'];
]]><![CDATA[$icq = $userinfo['user_icq'];
]]><![CDATA[$aim = $userinfo['user_aim'];
]]><![CDATA[$yim = $userinfo['user_yim'];
]]><![CDATA[$msnm = $userinfo['user_msnm'];
]]><![CDATA[$location = $userinfo['user_from'];
]]><![CDATA[$occupation = $userinfo['user_occ'];
]]><![CDATA[$interests = $userinfo['user_intrest'];
]]><![CDATA[$signature = $userinfo['user_sig'];
]]><![CDATA[$biography = $userinfo['user_bio'];
]]></screen><para>and can use them in the same manner as $currentlang above to build a highly customized header.<indexterm><primary>header</primary></indexterm></para><screen><![CDATA[
]]></screen></sect2>
<sect2 id="PHP-Nuke-header-change-logo"><title>How to change the logo in the <application>PHP-Nuke</application> header</title><para>One of the first things you will want to change once your <application>PHP-Nuke</application> is up and running, is the site's logo.<indexterm><primary>logo</primary></indexterm> For this, you only have to replace the logo.<indexterm><primary>logo</primary></indexterm>gif file that came with the theme you are using. Search for themes/YourTheme/logo.gif.<indexterm><primary>logo.gif</primary></indexterm> Whatever graphic you put in logo.gif,<indexterm><primary>logo.gif</primary></indexterm> it will show as the site's logo in the <application>PHP-Nuke</application> header.<indexterm><primary>header</primary></indexterm> </para><para>If you want to change the way the logo is displayed, perhaps by setting a width and height attribute, or specifying a border,<indexterm><primary>border</primary></indexterm> you will have to change the HTML code that displays it in the theme.<indexterm><primary>theme</primary></indexterm> To do this in a dynamic way, see <xref linkend="PHP-Nuke-header-change-logo-dynamic">. Here are the relevant code lines for each one of the standard <application>PHP-Nuke</application> themes:<indexterm><primary>themes</primary></indexterm></para><screen><![CDATA[./themes/3D-Fantasy/header.html:<a href="index.php"><img src="themes/3D-Fantasy/images/logo.gif" border="0"
]]><![CDATA[alt="Welcome to $sitename" align="left"></a>
]]><![CDATA[
]]><![CDATA[./themes/ExtraLite/theme.php: ."<a href=\"index.php\"><img src=\"themes/ExtraLite/images/logo.gif\"
]]><![CDATA[alt=\"Welcome to $sitename\" title=\"Welcome to $sitename\" border=\"0\"></a>"
]]><![CDATA[
]]><![CDATA[./themes/Kaput/theme.php: ."<a href=\"index.php\"><img src=\"themes/Kaput/images/logo.gif\" border=\"0\"
]]><![CDATA[alt=\""._WELCOMETO." $sitename\" align=\"left\"></a></td>"
]]><![CDATA[
]]><![CDATA[./themes/NukeNews/header.html:<a href="index.php">
]]><![CDATA[<img src="themes/NukeNews/images/logo.gif" align="left"
]]><![CDATA[alt=""._WELCOMETO." $sitename" border="0" hspace="10"></a></td>
]]><![CDATA[
]]><![CDATA[./themes/Odyssey/header.html:<a href="index.php">
]]><![CDATA[<img src="themes/Odyssey/images/logo.gif"
]]><![CDATA[alt=""._WELCOMETO." $sitename" border="0"></a>
]]><![CDATA[
]]><![CDATA[./themes/Slash/theme.php:<a href=$nukeurl>
]]><![CDATA[<img src=themes/Slash/images/logo.gif border=0></a>
]]><![CDATA[
]]><![CDATA[./themes/SlashOcean/theme.php:<a href=$nukeurl>
]]><![CDATA[<img src=themes/SlashOcean/images/logo.gif
]]><![CDATA[Alt=\"Welcome to $sitename\" border=0></a>
]]><![CDATA[
]]><![CDATA[./themes/Traditional/theme.php: ."<a href=\"index.php\">
]]><![CDATA[<img src=\"themes/Traditional/images/logo.gif\"
]]><![CDATA[alt=\""._WELCOMETO." $sitename\" border=\"0\"></a>"
]]><![CDATA[
]]><![CDATA[./themes/Anagram/theme.php: ."<a href=\"index.php\">
]]><![CDATA[<img src=\"themes/Anagram/images/logo.gif\" align=\"left\"
]]><![CDATA[alt=\""._WELCOMETO." $sitename\" border=\"0\"></a></td>\n"
]]><![CDATA[
]]><![CDATA[./themes/Karate/theme.php: ."<a href=\"index.php\">
]]><![CDATA[<img src=\"themes/Karate/images/logo.gif\" align=\"left\"
]]><![CDATA[alt=\""._WELCOMETO." $sitename\" border=\"0\"></a></td>\n"
]]><![CDATA[
]]><![CDATA[./themes/Milo/theme.php: ."<a href=\"index.php\">
]]><![CDATA[<img src=\"themes/Milo/images/logo.gif\" align=\"left\"
]]><![CDATA[alt=\""._WELCOMETO." $sitename\" border=\"0\"></a></td>\n"
]]><![CDATA[
]]><![CDATA[./themes/Sunset/theme.php:echo "<a href=$nuke_url>
]]><![CDATA[<img src=themes/Sunset/images/logo.gif
]]><![CDATA[Alt=\""._WELCOMETO." $sitename\" border=0></a>\n";
]]><![CDATA[
]]><![CDATA[./themes/DeepBlue/theme.php: ."<table border=0 width=100% cellpadding=0
]]><![CDATA[cellspacing=0><tr><td align=\"left\"><a href=\"index.php\">
]]><![CDATA[<img border=\"0\" src=\"themes/DeepBlue/images/logo.gif\"
]]><![CDATA[alt=\"Welcome to OpenMax!\" hspace=\"20\"></a></td><td align=\"right\">
]]><![CDATA[<img border=\"0\" src=\"themes/DeepBlue/images/logo-graphic.gif\"
]]><![CDATA[width=\"\"></td></tr></table></td></tr>\n"
]]></screen><para>This is also the place to put your change, if you want a second graphic besides your logo,<indexterm><primary>logo</primary></indexterm> or some other logo customization.</para><screen><![CDATA[
]]></screen></sect2>
<sect2 id="PHP-Nuke-header-change-logo-dynamic"><title>How to change the logo's dimensions dynamically</title><para>If you have designed a logo that can be displayed equally well at many resolutions and you wish to be able to change its display dimensions dynamically, according to the display resolution of your visitor's monitor,<indexterm><primary>monitor</primary></indexterm> then you have to use Javascript.<indexterm><primary>Javascript</primary></indexterm> This is because <acronym>PHP</acronym> is a server-based technology and the web server has no means of knowing the monitor resolution of a client requesting a page. It would have to query that client for the resolution it uses, get an answer, then create the page with the right logo dimensions. But HTTP is a stateless protocol,<indexterm><primary>protocol</primary></indexterm> meaning that, when the server gets an answer, it has no means to relate it to some previous request - not without cookies,<indexterm><primary>cookies</primary></indexterm> URL parameters, sessions and all that extra stuff. This is where Javascript comes into play, obviating the need for a query-and-answer procedure.<indexterm><primary>procedure</primary></indexterm></para><para>Substitute the image logo tag </para><para>&lt;img src=themes/YourTheme/images/logo.<indexterm><primary>logo</primary></indexterm>gif alt=&quot;&quot;._WELCOMETO.&quot; $sitename&quot; border=&quot;0&quot;&gt;</para><para>of your theme (see <xref linkend="PHP-Nuke-header-change-logo">) with the following:</para><screen><![CDATA[$mod_log = "images/my_logo.gif";
]]><![CDATA[echo ("<script>\n");
]]><![CDATA[echo ("var swidth='0';\n");
]]><![CDATA[echo ("swidth=screen.width\n");
]]><![CDATA[echo ("if ((swidth<=640)&&(swidth<800)){\n");
]]><![CDATA[echo ("document.write('<img src=$mod_logo width=500 border=0>')");
]]><![CDATA[echo ("}\n");
]]><![CDATA[echo ("else\n");
]]><![CDATA[echo ("if ((swidth>799)&&(swidth<1024)){\n");
]]><![CDATA[echo ("document.write('<img src=$mod_logo width=700 border=0>')");
]]><![CDATA[echo ("}\n");
]]><![CDATA[echo ("else\n");
]]><![CDATA[echo ("if (swidth>=1024){\n");
]]><![CDATA[echo ("document.write('<img src=$mod_logo width=900 border=0>')");
]]><![CDATA[echo ("}\n");
]]><![CDATA[echo ("</script>\n");
]]></screen><para>Change the location of your logo in the $mod_log variable. The code will echo this Javascript in place of the image tag:</para><screen><![CDATA[<script>
]]><![CDATA[var swidth='0';
]]><![CDATA[swidth=screen.width
]]><![CDATA[if ((swidth<=640)&&(swidth<800)){
]]><![CDATA[document.write('<img src=$mod_logo width=500 border=0>')");
]]><![CDATA[}
]]><![CDATA[else
]]><![CDATA[if ((swidth>799)&&(swidth<1024)){
]]><![CDATA[document.write('<img src=$mod_logo width=700 border=0>')");
]]><![CDATA[}
]]><![CDATA[else
]]><![CDATA[if (swidth>=1024){
]]><![CDATA[document.write('<img src=$mod_logo width=900 border=0>')");
]]><![CDATA[}
]]><![CDATA[</script>
]]></screen><para>which will be executed on the client's browser (if the client has Javascript<indexterm><primary>Javascript</primary></indexterm> enabled, of course). It will query its resolution (screen width) and write the HTML image tag, with the correct dimensions for the logo image, into the page's HTML code. It may not work though, if the client's security settings do not allow querying the screen's width. See <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=15307">Different themes for different resolutions</ulink> and <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=14147">banner next to logo</ulink> for a discussion of the details.</para></sect2>
<sect2 id="PHP-Nuke-header-change-banner-placement"><title>How to change placement of the banner in the <application>PHP-Nuke</application> header</title><para>Sometimes the banner will appear at a position that you would feel is unfavourable for your theme and overall appearence of your site (of course, only if you enabled the banner functionality in the administration panel,<indexterm><primary>panel</primary></indexterm> see <xref linkend="administration-functions">). The code that controls whether the banner will appear or not, is a few lines long:</para><screen><![CDATA[if ($banners == 1) {
]]><![CDATA[include("banners.php");
]]><![CDATA[}
]]></screen><para>and is found in the themeheader() function of the theme.<indexterm><primary>theme</primary></indexterm>php file. You don't need to bother about the included file, banners.<indexterm><primary>banners</primary></indexterm>php, that actually does all the job of selecting and displaying the appropriate banner,<indexterm><primary>banner</primary></indexterm> keeping banner statistics up-to-date and all that stuff. All you need is find out where to place those 3 lines in order to achieve the desired banner placement. As this is a highly theme dependent topic, there are no general recipes.<indexterm><primary>recipes</primary></indexterm> Just move the 3-liner around in themeheader() to get a feeling of the various elements and their positions, then experiment a little to find the right one for you. You might, for example, choose to include it in a table layout and echo it directly after the HTML &lt;body&gt; line:</para><screen><![CDATA[echo "<body bgcolor=\"#ffffff\" topmargin=\"0\"
]]><![CDATA[leftmargin=\"0\" marginheight=\"0\" marginwidth=\"0\">\n\n"
]]><![CDATA[."<table cellpadding=\"0\" cellspacing=\"0\"
]]><![CDATA[ width=\"100%\" border=\"0\" bgcolor=\"#6487dc\"><tr>\n"
]]><![CDATA[."<td bgcolor=\"#6487dc\" align=\"left\"
]]><![CDATA[ valign=\"top\" width=\"20%\"><br>
]]><![CDATA[<a href=\"index.php\"><img src=\"themes/subSilver/images/logo.gif\"
]]><![CDATA[ align=\"left\" alt=\""._WELCOMETO
]]><![CDATA[." $sitename\" border=\"0\"></a><br></td>\n"
]]><![CDATA[."</td><td bgcolor=\"#6487dc\" align=\"right\">";
]]><![CDATA[if ($banners) {
]]><![CDATA[ echo "<br>";
]]><![CDATA[ include("banners.php");
]]><![CDATA[ echo "<br>";
]]><![CDATA[}
]]></screen><para>See <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=237">Banner placement</ulink> and <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=14147">banner next to logo</ulink> for a discussion of banner placement in <application>PHP-Nuke</application>.</para></sect2>
<sect2 id="PHP-Nuke-header-watermark-background-image"><title>How to display a watermark background image</title><para>It may sound inconsistent (actually, it <emphasis>is</emphasis> inconsistent!), but in order to display a static background image (i.e. one that does not scroll down when you scroll), like a watermark, in PHP-Nuke, you must change the theheader() function in the theme.php file of your theme. <inlinemediaobject> <![ %output.print.png; [ <imageobject><imagedata fileref="./images/icon_eek.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject><imagedata fileref="icon_eek.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject><imagedata fileref="./images/icon_eek.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject><imagedata fileref="icon_eek.bmp" format="BMP"> </imageobject> ]]> <textobject><phrase>eek!</phrase> </textobject></inlinemediaobject> </para>
<para>The code you will need for this nice effect should be placed in the body part of the page's HTML code (the part delimited by the &lt;body&gt; and &lt;/body&gt; HTML tags). The reason we need this in the body part, is that in the header it will produce an error (at least in Mozilla):</para><screen><![CDATA[Error: document.body has no properties
]]></screen><para>This is probably because the document body does not exist at the time the header is loading. </para><para>Our code is a small Javascript, so you might think it belongs to the javascript.<indexterm><primary>javascript</primary></indexterm>php file under the includes folder (see <xref linkend="javascript-php">). Unfortunately, whatever is in that javascript.<indexterm><primary>javascript</primary></indexterm>php file, will be included in the HTML header of the page, i.e. the part of the HTML code delimited by the &lt;head&gt; and &lt;/head&gt; tags (see <xref linkend="modifying-php-nuke-html-header">), so this will not serve our purpose. What we actually need is a file for code that belongs to the HTML body and comes preferably immediately after the &lt;body&gt; tag - but such a file does not exist in <application>PHP-Nuke</application> yet. </para><para>Thus, the next best place to insert our Javascript is in the theme.<indexterm><primary>theme</primary></indexterm>php file of our theme.<indexterm><primary>theme</primary></indexterm> This is because the &lt;body&gt; tag is echoed precisely in this file, as <xref linkend="tab-body-tags"> demonstrates<footnote><para>Of course, this also means that our change has to be applied for every theme and after every upgrade anew. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_frown.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_frown.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_frown.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_frown.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject></para>
</footnote>.</para><para><table id="tab-body-tags"><title>&lt;body&gt; tags in theme.<indexterm><primary>theme</primary></indexterm>php of various themes</title><tgroup cols="2" colsep="1" rowsep="1">
<colspec colname="col0" align="left">
<colspec colname="col1" align="left">
<tbody>
<row>
<entry align="left" valign="top"><para>theme.php file</para></entry>
<entry align="left" valign="top"><para>PHP code that echoes the &lt;body&gt; tag for the theme</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>themes/3D-Fantasy/theme.php</para></entry>
<entry align="left" valign="top"><para>echo &quot;&lt;body bgcolor=\&quot;#ffffff\&quot; text=\&quot;#000000\&quot; link=\&quot;#363636\&quot; vlink=\&quot;#363636\&quot; alink=\&quot;#d5ae83\&quot;&gt;&lt;br&gt;\n\n\n&quot;;</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>themes/Anagram/theme.php</para></entry>
<entry align="left" valign="top"><para>echo &quot;&lt;body bgcolor=\&quot;#ffffff\&quot; text=\&quot;#000000\&quot;&gt;\n&quot;;</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>themes/DeepBlue/theme.php</para></entry>
<entry align="left" valign="top"><para>echo &quot;&lt;body bgcolor=\&quot;#0E3259\&quot; text=\&quot;#000000\&quot; link=\&quot;0000ff\&quot;&gt;&quot;</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>themes/ExtraLite/theme.php</para></entry>
<entry align="left" valign="top"><para>echo &quot;&lt;body text=\&quot;000000\&quot; link=\&quot;0000ff\&quot; vlink=\&quot;0000ff\&quot;&gt;&quot;</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>themes/Kaput/theme.php</para></entry>
<entry align="left" valign="top"><para>echo &quot;&lt;body bgcolor=\&quot;#FFFFFF\&quot; text=\&quot;#000000\&quot; link=\&quot;#363636\&quot; vlink=\&quot;#363636\&quot; alink=\&quot;#d5ae83\&quot;&gt;\n&quot;</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>themes/Karate/theme.php</para></entry>
<entry align="left" valign="top"><para>echo &quot;&lt;body bgcolor=\&quot;#ffffff\&quot; text=\&quot;#000000\&quot; link=\&quot;#363636\&quot; vlink=\&quot;#363636\&quot; alink=\&quot;#d5ae83\&quot;&gt;\n&quot;</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>themes/Milo/theme.php</para></entry>
<entry align="left" valign="top"><para>echo &quot;&lt;body bgcolor=\&quot;#ffffff\&quot; text=\&quot;#000000\&quot; link=\&quot;#363636\&quot; vlink=\&quot;#363636\&quot; alink=\&quot;#d5ae83\&quot;&gt;\n&quot;</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>themes/NukeNews/theme.php</para></entry>
<entry align="left" valign="top"><para>echo &quot;&lt;body bgcolor=\&quot;#505050\&quot; text=\&quot;#000000\&quot; link=\&quot;#363636\&quot; vlink=\&quot;#363636\&quot; alink=\&quot;#d5ae83\&quot;&gt;&quot;;</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>themes/Odyssey/theme.php</para></entry>
<entry align="left" valign="top"><para>echo &quot;&lt;body bgcolor=\&quot;#004080\&quot; text=\&quot;#000000\&quot; link=\&quot;#004080\&quot; vlink=\&quot;#004080\&quot; alink=\&quot;#004080\&quot;&gt;&quot;;</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>themes/Sand_Journey/theme.php</para></entry>
<entry align="left" valign="top"><para>echo &quot;&lt;body bgcolor=\&quot;$bgcolor1\&quot;&gt;&quot;;</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>themes/Slash/theme.php</para></entry>
<entry align="left" valign="top"><para>echo &quot;&lt;body bgcolor=DDDDDD text=222222 link=660000 vlink=222222&gt;</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>themes/SlashOcean/theme.php</para></entry>
<entry align="left" valign="top"><para>echo &quot;&lt;body bgcolor=FFFFFF text=000000 link=101070 vlink=101070&gt;</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>themes/Sunset/theme.php</para></entry>
<entry align="left" valign="top"><para>echo &quot;&lt;body bgcolor=\&quot;#FFC53A\&quot; text=\&quot;#000000\&quot; link=\&quot;#035D8A\&quot; vlink=\&quot;#035D8A\&quot;&gt;&quot;;</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>themes/Traditional/theme.php</para></entry>
<entry align="left" valign="top"><para>echo &quot;&lt;body bgcolor=\&quot;#FFFFFF\&quot; text=\&quot;#000000\&quot; link=\&quot;#000000\&quot; vlink=\&quot;#000000\&quot;&gt;&quot;</para></entry>
</row>
</tbody>
</tgroup></table></para><para>Find the line that echoes the &lt;body&gt; tag in your theme.<indexterm><primary>theme</primary></indexterm>php (look for the themeheader() function or consult <xref linkend="tab-body-tags">) and insert the following lines after it (if the line does not contain a semicolon at its end, you have of course to append these lines after the next most close line that contains it, otherwise you will mess up the code and get errors):</para><screen><![CDATA[ echo "\n";
]]><![CDATA[ echo "<script language=\"JavaScript1.2\">\n";
]]><![CDATA[ echo "<!--\n";
]]><![CDATA[ echo "if (document.all||document.getElementById) \n";
]]><![CDATA[ echo "document.body.style.background=
]]><![CDATA[ \"url('http://www.yoursite.com/images/watermark.gif')
]]><![CDATA[ white center no-repeat fixed\"\n";
]]><![CDATA[ echo "//-->\n";
]]><![CDATA[ echo "</script> \n";
]]></screen><para>Adapt the URL in the script (http://www.yoursite.com/images/watermark.<indexterm><primary>watermark</primary></indexterm>gif) to reflect the full URL to your watermark image. That's all, if your theme does not define any background colours for tables! </para><para>In practice, however, your theme <emphasis>will</emphasis> define at least two table background colours,<indexterm><primary>colours</primary></indexterm> those in the OpenTable() and OpenTable2() functions, as shown in this example, taken from the ExtraLite<indexterm><primary>ExtraLite</primary></indexterm> theme:<indexterm><primary>theme</primary></indexterm></para><screen><![CDATA[function OpenTable() {
]]><![CDATA[ global $bgcolor1, $bgcolor2;
]]><![CDATA[ echo "<table width=\"100%\" border=\"0\"
]]><![CDATA[ cellspacing=\"1\" cellpadding=\"0\"
]]><![CDATA[ bgcolor=\"$bgcolor2\"><tr><td>\n";
]]><![CDATA[ echo "<table width=\"100%\" border=\"0\"
]]><![CDATA[ cellspacing=\"1\" cellpadding=\"8\"
]]><![CDATA[ bgcolor=\"$bgcolor1\"><tr><td>\n";
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[function OpenTable2() {
]]><![CDATA[ global $bgcolor1, $bgcolor2;
]]><![CDATA[ echo "<table border=\"0\"
]]><![CDATA[ cellspacing=\"1\" cellpadding=\"0\"
]]><![CDATA[ bgcolor=\"$bgcolor2\" align=\"center\"><tr><td>\n";
]]><![CDATA[ echo "<table border=\"0\"
]]><![CDATA[ cellspacing=\"1\" cellpadding=\"8\"
]]><![CDATA[ bgcolor=\"$bgcolor1\"><tr><td>\n";
]]><![CDATA[}
]]></screen><para>You must delete those bgcolor attributes completely for this method to work! In fact, this will not be enough: you will have to delete every other table bgcolor attribute that appears in your theme.<indexterm><primary>theme</primary></indexterm>php<footnote><para>That is at least the way I managed to get it to work with the ExtraLight theme. Since everyt heme is different, you will have to experiment here.</para></footnote>. Contrary to what is implied in <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=14233">Static Background Image</ulink>, where this method is described in detail, deleting only the bgcolor attributes<indexterm><primary>attributes</primary></indexterm> for the above two OpenTable functions will not be enough.</para><tip>
<title>
Alternative solution
</title>
<para>
An alternative solution would be to add the background and bgproperties attributes directly in the &lt;body&gt; tags of the lines in <xref linkend="tab-body-tags">, as in this example for the ExtraLite theme:
</para>
<screen>
<![CDATA[echo "<body background=\"images/watermark.gif\" bgproperties=\"fixed\" ]]>
<![CDATA[text=\"000000\" link=\"0000ff\" vlink=\"0000ff\">"]]>
</screen>
<para>
bgproperties will also create a "watermark" on the page, a background image which does not scroll with the rest of the page (see <ulink url="http://htmlcodetutorial.com/document/_BODY_BGPROPERTIES.html">bgproperties attribute</ulink>. The only value it can attain is &ldquo;fixed&rdquo; and it must be used in conjunction with the background attribute. It is an MSIE extension, so use it, but don't rely on it. You will again have to delete all background colour attributes of the tables in theme.php. Contrary to the first method, however, there is no way to specify a no-repeat property, so that if your image does not fill the whole background space available (which depends on the client's monitor resolution), it will be repeated horizontally as well as vertically.
</para>
</tip>
</sect2>
<sect2 id="PHP-Nuke-header-display-flash-object"><title>How to display a Flash object in the <application>PHP-Nuke</application> header</title><para>To show Flash in the <application>PHP-Nuke</application> header,<indexterm><primary>header</primary></indexterm> you simply have to echo the appropriate HTML code. Since the HTML code for a Flash object is something like</para><screen><![CDATA[<object classid=\"clsid:D27CDB6E-AE6D-11cf-96B8-444553540000\"
]]><![CDATA[codebase=\"http://download.macromedia.com/pub/shockwave/cabs/
]]><![CDATA[flash/swflash.cab#version=6,0,29,0\" width=\"350\" height=\"100\">
]]><![CDATA[<param name=\"movie\" value=\"yourMovie.swf\">
]]><![CDATA[<param name=quality value=high>
]]><![CDATA[<embed src=\"yourMovie.swf\" quality=high pluginspage=\"http://www.macromedia.com/shockwave/download/
]]><![CDATA[index.cgi?P1_Prod_Version=ShockwaveFlash\" type=\"application/x-shockwave-flash\"
]]><![CDATA[width=\"350\" height=\"100\"></embed>
]]><![CDATA[</object>
]]></screen><para>the <application>PHP-Nuke</application> header code should contain something like</para><screen><![CDATA[echo "<object classid=\"clsid:D27CDB6E-AE6D-11cf-96B8-444553540000\" codebase=\"http://download.macromedia.com/pub/shockwave/cabs/
]]><![CDATA[flash/swflash.cab#version=6,0,29,0\" width=\"350\" height=\"100\"> "
]]><![CDATA[."<param name=\"movie\" value=\"yourMovie.swf\"> "
]]><![CDATA[."<param name=quality value=high> "
]]><![CDATA[."<embed src=\"yourMovie.swf\" quality=high pluginspage=\"http://www.macromedia.com/shockwave/download/
]]><![CDATA[index.cgi?P1_Prod_Version=ShockwaveFlash\" type=\"application/x-shockwave-flash\"
]]><![CDATA[width=\"350\" height=\"100\"></embed>"
]]><![CDATA[."</object>";
]]></screen><para>You can put the above code in the themes/YourTheme/theme.<indexterm><primary>theme</primary></indexterm>php file, in the themeheader() function,<indexterm><primary>function</primary></indexterm> after the call to the banners code:</para><screen><![CDATA[if ($banners == 1) {
]]><![CDATA[ include("banners.php");
]]><![CDATA[}
]]><![CDATA[...put Flash code ("echo") here...
]]></screen><para>The Flash object will be displayed after the banner,<indexterm><primary>banner</primary></indexterm> if you have one. See <xref linkend="flash-php-nuke-blocks"> on how to show Flash in a <application>PHP-Nuke</application> block.<indexterm><primary>block</primary></indexterm></para></sect2>
<sect2 id="hide-left-blocks"><title>How to hide the left blocks</title><para>For some esoteric reason, you may want to hide the column with the <emphasis>left</emphasis> blocks, although it contains some crucial blocks, like the modules block<indexterm><primary>block</primary></indexterm> (<xref linkend="fig-modules-block">), for example. To accomplish this, you have to edit the themeheader() function in the theme.<indexterm><primary>theme</primary></indexterm>php file of your theme (in the themes/YourTheme folder) and replace the line:</para><screen><![CDATA[blocks(left);
]]></screen><para>with</para><screen><![CDATA[if ($name=='Forums') {
]]><![CDATA[ /* Don't display it. */
]]><![CDATA[}
]]><![CDATA[else {
]]><![CDATA[ blocks(left);
]]><![CDATA[}
]]></screen><para>Here, we check if the module is the Forums module and suppress the call to blocks(left) if it is. This will hide the left column blocks in the Forums. It is easy to include more modules,<indexterm><primary>modules</primary></indexterm> as in the following example (see <ulink url="http://www.nukecops.com/postx69-0-0.html">Hide left blocks when viewing Forum or ANY module</ulink>, <ulink url="http://www.desarrollonuke.org/modules.php?name=Content&amp;pa=showpage&amp;pid=16">Como eliminar los bloques de la izquierda</ulink>, <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=18282">Left Blocks on Index Page only</ulink>):</para><screen><![CDATA[if ($name=='Forums' || $name=='Members_List' || $name=='Private_Messages') {
]]><![CDATA[ /* Don't display it. */
]]><![CDATA[} else {
]]><![CDATA[ blocks(left);
]]><![CDATA[}
]]></screen><para>Don't forget to add $name to the list of global variables in themeheader():</para><screen><![CDATA[global $user, $banners, $sitename, $slogan, $cookie, $prefix, $dbi, $name;
]]></screen><para>Of course, if you don't find the call to blocks(left), your theme already suppresses the left column of blocks. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
<tip>
<title>
How to hide the right blocks
</title>
<para>
Most of the time, if you want to hide any blocks, they will be the blocks in the right column, not the blocks in the left. See <xref linkend="hide-right-blocks"> on how to hide the right blocks.
</para>
</tip>
<para>From a theme design point of view, the above solution does not look satisfactory: you have to hardcode the names of the modules that should not display the left blocks into the code of the theme.<indexterm><primary>theme</primary></indexterm> Since you don't know in advance which ones these are, you create a dependency<indexterm><primary>dependency</primary></indexterm> relation to all existing and future modules.<indexterm><primary>modules</primary></indexterm></para><para>A cleaner, alternative way is to declare the global $hideleft variable in themeheader() and check its value instead:</para><screen><![CDATA[global $hideleft;
]]><![CDATA[...
]]><![CDATA[if($hideleft == 1){
]]><![CDATA[ /* Don't display it. */
]]><![CDATA[} else {
]]><![CDATA[ blocks(left);
]]><![CDATA[}
]]></screen><para>Now, for every module that you want to hide the left blocks, insert the lines</para><screen><![CDATA[global $hideleft;
]]><![CDATA[$hideleft =1;
]]></screen><para>at the beginning of its code. As you see, with this method, the selection of the modules that hide the left blocks has become the job the modules' authors. The theme code can work with any module,<indexterm><primary>module</primary></indexterm> present or future one, without changes - as any theme should.</para><tip>
<title>
More flexibility with the Block Modificator
</title>
<para>
With Chris Sengers' <ulink url="http://www.sengers-au.com/Portal/main/modules.php?name=Downloads&amp;d_op=viewdownload&amp;cid=5">Simple Blocks Manipulator for left blocks</ulink> you can put any block left or right differently with any module. You can even use inactive blocks and also change the theme according to the module (we show how to do this yourself in <xref linkend="change-php-nuke-theme-depending-on-module">).
</para>
</tip>
</sect2>
</sect1>
<sect1 id="php-nuke-theme-modifying-body"><title>Modifying the <application>PHP-Nuke</application> theme body</title><para>In this section we continue our study of <application>PHP-Nuke</application> themes - this time with the body of a theme! We cover topics like:</para><itemizedlist><listitem><para>How to get multipage News articles (<xref linkend="multipage-news-articles">).</para></listitem><listitem><para>How to change the background colour (<xref linkend="change-background-colour">).</para></listitem></itemizedlist><sect2 id="multipage-news-articles"><title>How to get multipage News articles</title><para>It appears that while Reviews,<indexterm><primary>Reviews</primary></indexterm> Section, and Content areas allow multipage bodies, the general News article does not. Contrary to what one would think, if you want to add such functionality<indexterm><primary>functionality</primary></indexterm> in the News module,<indexterm><primary>module</primary></indexterm> the code under modules/News/ is <emphasis>not</emphasis> the right place. The right place is the themearticle() in the theme.<indexterm><primary>theme</primary></indexterm>php file of your theme!</para><para>This is so, because it is the themearticle() function that outputs the article<indexterm><primary>article</primary></indexterm> text, through a call to the FormatStory() function (which is also defined in theme.<indexterm><primary>theme</primary></indexterm>php):</para><screen><![CDATA[FormatStory($thetext, $notes="", $aid, $informant);
]]></screen><para>Thus, all we have to do is format $thetext accordingly, before it is passed to FormatStory. Just add the following code to the begining of the themearticle() function<indexterm><primary>function</primary></indexterm> in theme.<indexterm><primary>theme</primary></indexterm>php, like this<footnote><para>Notice that we have added $page to the global variable list - other than that ,the first two lines are included here only for your orientation.</para></footnote> (see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?topic=12114&amp;forum=42">Multipage articles</ulink>, <ulink url="http://www.nukeforums.com/forums/viewtopic.php?topic=9390&amp;forum=26">Pagebreaks in articles</ulink>):</para><screen><![CDATA[function themearticle ($aid, $informant, $datetime, $title, $thetext,
]]><![CDATA[$topic, $topicname, $topicimage, $topictext) {
]]><![CDATA[global $admin, $sid, $tipath, $page;
]]><![CDATA[$contentpages = explode( "<!--pagebreak-->", $thetext );
]]><![CDATA[$pageno = count($contentpages);
]]><![CDATA[if ( $page=="" || $page < 1 )
]]><![CDATA[$page = 1;
]]><![CDATA[if ( $page > $pageno )
]]><![CDATA[$page = $pageno;
]]><![CDATA[$arrayelement = (int)$page;
]]><![CDATA[$arrayelement --;
]]><![CDATA[if ($pageno > 1) {
]]><![CDATA[$thetextNew .= "Page: $page/$pageno<br>";
]]><![CDATA[}
]]><![CDATA[$thetextNew .= "<p align=\"justify\">$contentpages[$arrayelement]</p>";
]]><![CDATA[if($page >= $pageno) {
]]><![CDATA[$next_page = "";
]]><![CDATA[} else {
]]><![CDATA[$next_pagenumber = $page + 1;
]]><![CDATA[if ($page != 1) {
]]><![CDATA[$next_page .= "- ";
]]><![CDATA[}
]]><![CDATA[$next_page .= "<a href=\"modules.php?name=News&file=article&sid=$sid
]]><![CDATA[&page=$next_pagenumber\">"._NEXT." ($next_pagenumber/$pageno)</a>
]]><![CDATA[<a href=\"modules.php?name=News&file=article&sid=$sid&page=$next_pagenumber\">
]]><![CDATA[<img src=\"images/right.gif\"border=\"0\" alt=\""._NEXT."\"></a>";
]]><![CDATA[}
]]><![CDATA[if ($page == $pageno) {
]]><![CDATA[$thetextNew .= "<br><p align=\"justify\">".nl2br($mypage[page_footer])."</p><br><br>";
]]><![CDATA[}
]]><![CDATA[if($page <= 1) {
]]><![CDATA[$previous_page = "";
]]><![CDATA[} else {
]]><![CDATA[$previous_pagenumber = $page - 1;
]]><![CDATA[$previous_page = "<a href=\"modules.php?name=News&file=article&sid=$sid
]]><![CDATA[&page=$previous_pagenumber\">
]]><![CDATA[<img src=\"images/left.gif\" border=\"0\" alt=\""._PREVIOUS."\"></a>
]]><![CDATA[<a href=\"modules.php?name=News&file=article&sid=$sid
]]><![CDATA[&page=$previous_pagenumber\">"._PREVIOUS." ($previous_pagenumber/$pageno)</a>";
]]><![CDATA[}
]]><![CDATA[$thetextNew .= "<br><br><br><center>$previous_page $next_page</center><br><br>";
]]><![CDATA[$thetext = $thetextNew;
]]></screen><para>Now you can use &lt;!--pagebreak--&gt; in your News stories, and the code above will split the text at the &lt;!--pagebreak--&gt; and create the &ldquo;previous&rdquo; and &ldquo;next&rdquo; hyperlinks for you (don't forget to define _NEXT and _PREVIOUS in your language file, as shown in <xref linkend="modifying-PHP-Nuke-texts">).</para></sect2>
<sect2 id="change-background-colour"><title>How to change background colour</title><para>A well-constructed theme will offer you a simple way to change the various colours (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=311">How to change the background colour</ulink>): in the theme.<indexterm><primary>theme</primary></indexterm>php file of the NukeNews theme, for example, you can read:</para><screen><![CDATA[/************************************************************/
]]><![CDATA[/* Theme Colors Definition */
]]><![CDATA[/* */
]]><![CDATA[/* Define colors for your web site. $bgcolor2 is generaly */
]]><![CDATA[/* used for the tables border as you can see on OpenTable() */
]]><![CDATA[/* function, $bgcolor1 is for the table background and the */
]]><![CDATA[/* other two bgcolor variables follows the same criteria. */
]]><![CDATA[/* $texcolor1 and 2 are for tables internal texts */
]]><![CDATA[/************************************************************/
]]></screen><para>and immediately after that:</para><screen><![CDATA[$bgcolor1 = "#efefef";
]]><![CDATA[$bgcolor2 = "#cfcfbb";
]]><![CDATA[$bgcolor3 = "#efefef";
]]><![CDATA[$bgcolor4 = "#cfcfbb";
]]><![CDATA[$textcolor1 = "#000000";
]]><![CDATA[$textcolor2 = "#000000";
]]></screen><para>The strings to the right side of the above assignments are hexadecimal representations of colours.<indexterm><primary>colours</primary></indexterm> They begin with a # and contain six hexadecimal digits, two for each colour<indexterm><primary>colour</primary></indexterm> of the basic ones, red, green and blue. Thus, the string &quot;#cfcfbb&quot; fot $bgcolor4 means cf for red, cf for green and bb for blue. Each one of the three hexadecimal two-digit numbers has a range from 00 to FF (just as each hexadecimal digit goes from 0 to F: 0, 1, 2, 3..., 8, 9, a, b, c, d, e, f, where a means 10, b means 11, c means 12 ... and f means 15 in the hexadecimal system). This means a range from 0 to 255 - that's 256 different values for each colour.<indexterm><primary>colour</primary></indexterm> </para><tip>
<title>
Colour wheels
</title>
<para>
A useful tool in exploring the visible spectrum in HTML is the <ulink url="http://www.karakas-online.de/myServices/colorwheel.html">colour wheel</ulink>. Just hover over the wheel with your mouse to view 4096 colors in their web safe, web smart and unsafe versions.<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_cool.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_cool.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_cool.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_cool.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject>
</para>
<para>
You can also use the <ulink url="http://www.karakas-online.de/popups/">colour popups of the Tag-o-matic</ulink> to show all 216 web-safe colours in a virtual colour card.
</para>
</tip>
<para>But what do you do if your theme does not follow this scheme and does not offer you this possibility? In such a case, we need to applly our knowledge<indexterm><primary>knowledge</primary></indexterm> on the structure of a theme (see <xref linkend="topic-structure">). We have seen that each theme comes with its own definition of the OpenTable() and CloseTable() functions. A brief look at the code of tables.<indexterm><primary>tables</primary></indexterm>php in modules/NukeNews reveals the place where $bgcolor1 and $bgcolor2 are used in the Nuke News theme:<indexterm><primary>theme</primary></indexterm> in the definitions of OpenTable() and CloseTable()! This is for example the OpenTable() function for the NukeNews theme (see modules/NukeNews/tables.<indexterm><primary>tables</primary></indexterm>php):</para><screen><![CDATA[function OpenTable() {
]]><![CDATA[ global $bgcolor1, $bgcolor2;
]]><![CDATA[ echo "<table width=\"100%\" border=\"0\" cellspacing=\"1\"
]]><![CDATA[ cellpadding=\"0\" bgcolor=\"$bgcolor2\"><tr><td>\n";
]]><![CDATA[ echo "<table width=\"100%\" border=\"0\" cellspacing=\"1\"
]]><![CDATA[ cellpadding=\"8\" bgcolor=\"$bgcolor1\"><tr><td>\n";
]]><![CDATA[}
]]></screen><para>Other themes construct their the OpenTable() and CloseTable() functions similarly, if not identically. We will use this fact to change the background colour in the Stories Archive module - and only there. To this end, we only need to define new OpenTable() and CloseTable() functions, with the colour of our choice, then use the new functions instead of the old ones everywhere in the module:<indexterm><primary>module</primary></indexterm></para><para>In the theme.<indexterm><primary>theme</primary></indexterm>php file of your theme, add the following two functions<footnote><para>Strictly seen, the CloseTableNew() function is not necessarily needed, since no new colour is defined there, but it is good to have, to keep the functions conceptually separated from the standard ones.</para></footnote>:</para><screen><![CDATA[function OpenTableNew() {
]]><![CDATA[ global $bgcolor1, $bgcolor2;
]]><![CDATA[ echo "<table width=\"100%\" border=\"0\" cellspacing=\"1\"
]]><![CDATA[ cellpadding=\"0\" bgcolor=\"$bgcolornew2\"><tr><td>\n";
]]><![CDATA[ echo "<table width=\"100%\" border=\"0\" cellspacing=\"1\"
]]><![CDATA[ cellpadding=\"8\" bgcolor=\"$bgcolornew1\"><tr><td>\n";
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[function CloseTableNew() {
]]><![CDATA[ echo "</td></tr></table></td></tr></table>\n";
]]><![CDATA[}
]]></screen><para>Give the new background colours,<indexterm><primary>colours</primary></indexterm> $bgcolornew1 and $bgcolornew2, the values of your liking in the start of theme.<indexterm><primary>theme</primary></indexterm>php, for example:</para><screen><![CDATA[$bgcolornew1 = "#ffffff";
]]><![CDATA[$bgcolornew2 = "#660000";
]]></screen><para>Then just change every occurence of &quot;OpenTable&quot; and &quot;CloseTable&quot; with &quot;OpenTable<indexterm><primary>OpenTable</primary></indexterm>New&quot; and &quot;CloseTableNew&quot; respectively in modules/Stories_Archive/index.php.<indexterm><primary>index.php</primary></indexterm> That's all! The Stories Archive module will now use the new colours.<indexterm><primary>colours</primary></indexterm></para><para>There is one small detail you may also want to fix though: the colours of the cells for the &ldquo;Articles | Comments | Reads | Score | Date | Actions&rdquo; links. To change those too, you will have to change the $bgcolour2 colour in the table cells of the show_month function of modules/Stories_Archive/index.php<indexterm><primary>index.php</primary></indexterm> (see also <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=12974">Background color in Stories Archive</ulink>):</para><screen><![CDATA[ echo "<table border=\"0\" width=\"100%\"><tr>"
]]><![CDATA[ ."<td bgcolor=\"$bgcolor2\" align=\"left\"><b>"._ARTICLES."</b></td>"
]]><![CDATA[ ."<td bgcolor=\"$bgcolor2\" align=\"center\"><b>"._COMMENTS."</b></td>"
]]><![CDATA[ ."<td bgcolor=\"$bgcolor2\" align=\"center\"><b>"._READS."</b></td>"
]]><![CDATA[ ."<td bgcolor=\"$bgcolor2\" align=\"center\"><b>"._USCORE."</b></td>"
]]><![CDATA[ ."<td bgcolor=\"$bgcolor2\" align=\"center\"><b>"._DATE."</b></td>"
]]><![CDATA[ ."<td bgcolor=\"$bgcolor2\" align=\"center\"><b>"._ACTIONS."</b></td></tr>";
]]></screen><para>For your design to be consistent, the best way would be to change the six occurences of $bgcolor2 in the above code, to your new background colour<indexterm><primary>colour</primary></indexterm> $bgcolornew2. </para><para>If you want to change the <emphasis>foreground<indexterm><primary>foreground</primary></indexterm></emphasis> colour,<indexterm><primary>colour</primary></indexterm> the easiest method might be to change the value of the text attribute in the &lt;body&gt; tag that is echoed in the themeheader() function of theme.<indexterm><primary>theme</primary></indexterm>php (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=378">How to change the main font color</ulink>):</para><screen><![CDATA[echo "<body bgcolor=\"#505050\" text=\"#000000\"
]]><![CDATA[link=\"#363636\" vlink=\"#363636\" alink=\"#d5ae83\">";
]]></screen><para>Setting</para><screen><![CDATA[text=\"#FF0000\"
]]></screen><para>for example, should make all text appear in red. </para></sect2>
</sect1>
<sect1 id="php-nuke-theme-modifying-index"><title>Modifying the <application>PHP-Nuke</application> theme index</title><para>The themeindex() function displays and formats the News articles. In its standard form, it will attribute a news article to the administrator,<indexterm><primary>administrator</primary></indexterm> rather than the registered user who submitted it. It would be nice if the &ldquo;Posted by&rdquo; string pointed to the real author, not the administrator who approved and posted the submission (see <xref linkend="fig-posted-by">).</para><para>
<figure id="fig-posted-by">
<title>
News article: &ldquo;posted by&rdquo; does not mean &ldquo;submitted by&rdquo;.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1132;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1132;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1132;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1132;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>News article: &ldquo;posted by&rdquo; does not mean &ldquo;submitted by&rdquo;.</phrase>
</textobject>
<caption>
<para>News article: &ldquo;posted by&rdquo; does not mean &ldquo;submitted by&rdquo;.</para>
</caption>
</mediaobject>
</figure>
</para><para>To give credit,<indexterm><primary>credit</primary></indexterm> where credit is due, you must change function themeindex() in the file theme.<indexterm><primary>theme</primary></indexterm>php of your theme, e.g. themes/NukeNews/theme.<indexterm><primary>theme</primary></indexterm>php. Change the following:</para><screen><![CDATA[ if ("$aid" == "$informant") {
]]><![CDATA[ $content = "$thetext$notes\n";
]]><![CDATA[ } else {
]]><![CDATA[ if($informant != "") {
]]><![CDATA[ $content = "<a href=\"modules.php?name=Your_Account
]]><![CDATA[ &amp;op=userinfo&amp;username=$informant\">$informant</a> ";
]]><![CDATA[ } else {
]]><![CDATA[ $content = "$anonymous ";
]]><![CDATA[ }
]]><![CDATA[ $content .= ""._WRITES." <i>\"$thetext\"</i>$notes\n";
]]><![CDATA[ }
]]><![CDATA[ $posted = ""._POSTEDBY." ";
]]><![CDATA[ $posted .= get_author($aid);
]]></screen><para>to:</para><screen><![CDATA[ $content = "$thetext$notesn";
]]><![CDATA[ $posted = ""._POSTEDBY." ";
]]><![CDATA[ if("$informant" == "") {
]]><![CDATA[ $posted .= "$anonymous ";
]]><![CDATA[ } else {
]]><![CDATA[ $posted .= get_author($informant);
]]><![CDATA[ }
]]><![CDATA[
]]></screen><para>or, if you want to be more flexible, to:</para><screen><![CDATA[if ($informant == "") {
]]><![CDATA[ $informant = "Anonymous";
]]><![CDATA[}else {
]]><![CDATA[ $holder = sql_query("SELECT url, femail
]]><![CDATA[ FROM ".$user_prefix."_users where uname='$informant'", $dbi);
]]><![CDATA[ list($url, $femail) = sql_fetch_row($holder, $dbi);
]]><![CDATA[ if ($url != "") {
]]><![CDATA[ $informant = "<a href="$url">$aid</a>";
]]><![CDATA[ } elseif ($femail != "") {
]]><![CDATA[ $informant = "<a href="mailto:$femail">$informant</a>";
]]><![CDATA[ } else {
]]><![CDATA[ $informant = "<a href="modules.php?name=Your_Account
]]><![CDATA[ &op=userinfo&uname=$informant">$aid</a>";
]]><![CDATA[ }
]]><![CDATA[}
]]><![CDATA[echo "$informant";
]]><![CDATA[
]]></screen><para>If you apply the latter solution, you should also declare $user_prefix and $dbi to be global variables in themeindex(). </para><caution>
<title>
Every theme is different!
</title>
<para>
Not all themes are like the NukeNews theme. Some may format the "Posted by" string in a separate function. The important thing to remember is that you must find the line
</para>
<screen>
<![CDATA[$posted = ""._POSTEDBY." ";]]>
</screen>
<para>
in the themeindex() function. The name of the &ldquo;informant&rdquo; is echoed immediately after that line. That's the place to include the above pieces of code (perhaps replacing some function call).
</para>
</caution>
<para>See <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=14121">submit news problem</ulink> and <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=12588">Need to change some links</ulink> for further discussion of this topic.</para><para>The themeindex() function in theme.<indexterm><primary>theme</primary></indexterm>php is also the place where the &ldquo;number of reads<indexterm><primary>ads</primary></indexterm>&rdquo; is printed after the &ldquo;posted by&rdquo; part (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=386">How to remove the number of reads in News</ulink>). Thus, if you want to remove the number of reads in the News module and your theme is NukeNews, for example, you have to edit themes/NukeNews/theme.<indexterm><primary>theme</primary></indexterm>php with a <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=122">decent text editor</ulink> (see also <xref linkend="editing-PHP-Nuke-files">), find the line</para><screen><![CDATA[$posted .= " "._ON." $time $timezone ($counter "._READS.")";
]]></screen><para>in the themeindex() function and change it to:</para><screen><![CDATA[$posted .= " "._ON." $time $timezone ";
]]></screen></sect1>
<sect1 id="php-nuke-theme-modifying-footer"><title>Modifying the <application>PHP-Nuke</application> theme footer</title><itemizedlist><listitem><para><xref linkend="insert-right-extra-table"></para></listitem><listitem><para><xref linkend="PHP-Nuke-Copyright-notice"></para></listitem></itemizedlist><para>Here is a little unorthodox example of what you can achieve by modifying the theme footer:<indexterm><primary>footer</primary></indexterm> </para><para>Suppose you just wonder how you can make a new table to the right of each page (<xref linkend="insert-right-extra-table">), perhaps because you want to put an advertisement table there. The standard way to do this would be to write a <application>PHP-Nuke</application> block (see <xref linkend="blocks">), insert it in <application>PHP-Nuke</application> through the block management panel (see <xref linkend="admin-management">), position it in the right column, then define its relative position to the other blocks in the right column through the intuitive graphical arrows<indexterm><primary>arrows</primary></indexterm> in the block table of the block management panel.<indexterm><primary>panel</primary></indexterm></para><para>An alternative way is to edit your theme.<indexterm><primary>theme</primary></indexterm>php. There, in the function themefooter(), you should see an IF statement for the blocks(right):</para><screen><![CDATA[if ($index == 1) {
]]><![CDATA[ $tmpl_file = "themes/NukeNews/center_right.html";
]]><![CDATA[ $thefile = implode("", file($tmpl_file));
]]><![CDATA[ $thefile = addslashes($thefile);
]]><![CDATA[ $thefile = "\$r_file=\"".$thefile."\";";
]]><![CDATA[ eval($thefile);
]]><![CDATA[ print $r_file;
]]><![CDATA[ blocks(right);
]]><![CDATA[}
]]></screen><para>The $index variable controls whether the right column should be displayed at all (together with all the blocks that were positioned &ldquo;right&rdquo;). If it is equal to 1, the right column should be visible and a call to blocks(right) is made. </para><para>You can echo the HTML for the extra table cell after this IF block.<indexterm><primary>block</primary></indexterm> This extra table cell will be visible in all pages and could contain a <application>PHP-Nuke</application> block with Google skyscraper ad (<xref linkend="advertisements-in-php-nuke-blocks">), or any other content of your choice. See <xref linkend="insert-right-extra-table"> for the details.</para><tip>
<title>
What makes right blocks disappear...
</title>
<para>
...is the theme footer, as you can see from the code above! It is in the themefooter() function of theme.php in your theme folder where the value of $index is checked and blocks(right) is called to display the right blocks. If blocks(right) and the statements around it are called unconditionally, then the right blocks will never disappear, no matter what value $index has, and the method of <xref linkend="hide-right-blocks"> will not work. You will then have to adjust themefooter() in your theme manually. See also <ulink url="http://www.nukeforums.com/forums/viewtopic.php?p=59094">Disable right blocks in News Module</ulink>.
</para>
</tip>
<sect2 id="insert-right-extra-table"><title>How to insert an extra table to the right of the page</title><para>The themefooter() function in the theme.<indexterm><primary>theme</primary></indexterm>php file of your theme is the right place to modify if you want to insert an extra table cell to the right of your page:</para><para>Find the call to blocks(right) (see it in <xref linkend="php-nuke-theme-modifying-footer">) and modify it by adding code as follows:</para><screen><![CDATA[blocks(right);
]]><![CDATA[ }
]]><![CDATA[ echo "</td><td>&nbsp;</td>";
]]><![CDATA[ echo "<td>Some text here.";
]]><![CDATA[
]]><![CDATA[ // This is an extra table cell now
]]><![CDATA[
]]><![CDATA[ $footer_message = "$foot1<br>$foot2<br>$foot3<br>$foot4";
]]><![CDATA[ $tmpl_file = "themes/fiblack/footer.html";
]]><![CDATA[ $thefile = implode("", file($tmpl_file));
]]><![CDATA[ $thefile = addslashes($thefile);
]]><![CDATA[ $thefile = "$r_file="".$thefile."";";
]]><![CDATA[ eval($thefile);
]]><![CDATA[ print $r_file;
]]><![CDATA[}
]]></screen><para>Or, as a more elaborate variation that includes an external piece of code (in this case the Login block):</para><screen><![CDATA[blocks(right);
]]><![CDATA[ }
]]><![CDATA[ echo "</td><td>&nbsp;</td>";
]]><![CDATA[ echo "<td>Some text here.<br>";
]]><![CDATA[ include("blocks/block-Login.php");
]]><![CDATA[ $title = "Title Here";
]]><![CDATA[ themesidebox($title,$content);
]]><![CDATA[
]]><![CDATA[ // This is an extra table cell now
]]><![CDATA[
]]><![CDATA[ $footer_message = "$foot1<br>$foot2<br>$foot3<br>$foot4";
]]><![CDATA[ $tmpl_file = "themes/fiblack/footer.html";
]]><![CDATA[ $thefile = implode("", file($tmpl_file));
]]><![CDATA[ $thefile = addslashes($thefile);
]]><![CDATA[ $thefile = "$r_file="".$thefile."";";
]]><![CDATA[ eval($thefile);
]]><![CDATA[ print $r_file;
]]><![CDATA[}
]]></screen><para>In both cases, it is important that the inserted code is outside the IF statement that controls the call to blocks(right). See <ulink url="http://www.nukeforums.com/forums/viewtopic.php?topic=11461&amp;forum=42">Insert a new table</ulink> for more details.</para></sect2>
<sect2 id="PHP-Nuke-Copyright-notice"><title>The <application>PHP-Nuke</application> Copyright notice</title><para>The theme footer also is the place where the <application>PHP-Nuke</application> copyright notice comes in. You don't need to do anything for this, it is done automatically as follows (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=100">PHP-Nuke Copyright and Logo</ulink>): </para><para>The function themefooter() in theme.<indexterm><primary>theme</primary></indexterm>php contains a call to the footmsg() function,<indexterm><primary>function</primary></indexterm> as in the following example from the Milo theme (file themes/Milo/theme.php):</para><screen><![CDATA[ echo "</td>\n"
]]><![CDATA[ ."</tr></table>\n"
]]><![CDATA[ ."<table bgcolor=\"#000000\" width=\"750\"
]]><![CDATA[ cellpadding=\"0\" cellspacing=\"0\" border=\"0\" align=\"center\">\n"
]]><![CDATA[ ."<tr>\n"
]]><![CDATA[ ."<td width=\"750\" height=\"5\">
]]><![CDATA[ <img src=\"themes/Milo/images/bottombar.gif\" width=\"750\"
]]><![CDATA[ height=\"5\" border=\"0\" alt=\"\"></td>\n"
]]><![CDATA[ ."</tr>\n"
]]><![CDATA[ ."<tr>\n"
]]><![CDATA[ ."<td width=\"100%\"><img src=\"themes/Milo/images/pixel.gif\"
]]><![CDATA[ width=\"1\" height=\"1\" border=\"0\" alt=\"\"></td>\n"
]]><![CDATA[ ."</tr>\n"
]]><![CDATA[ ."</table>\n"
]]><![CDATA[ ."<br>\n"
]]><![CDATA[ ."<br>\n"
]]><![CDATA[ ."<table width=\"750\" cellpadding=\"0\" cellspacing=\"0\"
]]><![CDATA[ border=\"0\" align=\"center\">\n"
]]><![CDATA[ ."<tr align=\"center\">\n"
]]><![CDATA[ ."<td width=\"100%\" colspan=\"3\">\n";
]]><![CDATA[ footmsg();
]]><![CDATA[ echo "</td>\n"
]]><![CDATA[ ."</tr>\n"
]]><![CDATA[ ."</table>\n";
]]></screen><para>footmsg, in turn, is defined in the footer.php file (located in the root<indexterm><primary>root</primary></indexterm> directory, together with config.php,<indexterm><primary>config.php</primary></indexterm> mainfile.php and the other important files). There, among some code that displays the computation time it took to display the page, we read:</para><screen><![CDATA[ // DO NOT REMOVE THE FOLLOWING COPYRIGHT LINE.
]]><![CDATA[ YOU'RE NOT ALLOWED TO REMOVE NOR EDIT THIS.
]]><![CDATA[ echo "$copyright<br>$totaltime<br>\n</font>\n";
]]></screen><para>So that's the place where the Copyright notice for <application>PHP-Nuke</application> comes from! Does that mean that, now that we have found it, we are entitled to edit or remove it? Absolutely NOT! In the INSTALL file that comes with the <application>PHP-Nuke</application> package, Franzisco Burzi,<indexterm><primary>Burzi</primary></indexterm> the author of <application>PHP-Nuke</application> explicitly forbids this:</para><screen><![CDATA[##############################################################################
]]><![CDATA[# I M P O R T A N T N O T E #
]]><![CDATA[##############################################################################
]]><![CDATA[# IMPORTANT: I saw many sites that removes the copyright line in the footer #
]]><![CDATA[# of each page. YOU'RE NOT ALLOWED TO REMOVE NOR CHANGE/EDIT THAT NOTE. If I #
]]><![CDATA[# still see this problem happening I'll need to take extreme measures that #
]]><![CDATA[# can include: to change the <application>PHP-Nuke</application> license, to encrypt some parts of the #
]]><![CDATA[# code, stop distributing it for free and in an extreme case stop developing #
]]><![CDATA[# it. The decision is in your hands. #
]]><![CDATA[# If you do not agreed with this simple rule, delete all <application>PHP-Nuke</application> files #
]]><![CDATA[# rigth now and move away from it. Thanks. #
]]><![CDATA[##############################################################################
]]></screen><para>Still, even this simple and clear admonition from the author does not stop some folks to pose the same question in the forums again and again: Am I allowed to take the Copyright Notice away? The argument often presented<indexterm><primary>presented</primary></indexterm> is one that involves the Licence uder which <application>PHP-Nuke</application> is released, the <ulink url="http://www.gnu.org/copyleft/gpl.html">GNU General Public Licence</ulink> (GPL). If I am allowed to change the code under the GPL,<indexterm><primary>GPL</primary></indexterm> the argument goes, and the Copyright Notice is generated by a function call to footmsg(), why not just change the code and delete that call in my theme?<indexterm><primary>theme</primary></indexterm> I can do this, right?</para><para>Wrong. In an article titled <ulink url="http://phpnuke.org/modules.php?name=News&amp;file=article&amp;sid=4947">PHP-Nuke GPL Copyright Removal Question Finally Solved</ulink>, MissS writes:</para><blockquote><para>A while back, questions were raised as to whether or not the copyright notice at the bottom of PHPNuke created pages could be removed. Now there is an answer to this question, straight from the <acronym>GNU</acronym> people. </para><para>The <acronym>GNU</acronym> website states that if you have any questions concerning licensing, you can simply email them for clarification. That is exactly what I did and what follows is my email to them...</para></blockquote><para>So MissS wrote to licensing@gnu.org on Sept. 19th, 2002 and asked:</para><blockquote><para>I have a question about the GNU/GPL license. There is a program called <application>PHP-Nuke</application> that has been released under this license. (This program can be found at www.phpnuke.org) This program is a content management system that provides the structure for a website along with the means to administer that site. </para><para>What I would like to know is this: if I use this PHPNuke program to create my website,<indexterm><primary>website</primary></indexterm> must the copyright notice (that is included at the bottom of each page that is created with PHPNuke) remain there in order to remain in compliance with this license? There is also a copyright notice within the source code files themselves. </para></blockquote><para>Dave Turner's answer was clear, albeit somewhat lapidary:</para><blockquote><para>Yes. See section 2c of the GPL for details.</para></blockquote><para>MissS was also confused as to whether <application>PHP-Nuke</application> can be technically considered as what the GPL in its 2c section calls a program that &ldquo;normally reads commands interactively when run&rdquo; , in which case it must, among other things, &ldquo;print or display an announcement including an appropriate copyright notice&rdquo;:</para><blockquote><para>This subject came up a while back at PHPNuke.<indexterm><primary>PHPNuke</primary></indexterm>org and no-one seemed to know the real</para><para>answer. I have spent quite sometime reading over your license and can't definitively figure out</para><para>this answer for myself. (I had questions such as: is the output from a program like this truly</para><para>considered interactive or not?) </para><para>Please let me know. I don't want to remove the copyright footers on the output pages if I am</para><para>not legally allowed to do so. </para></blockquote><para>To which Dave Turner replied:</para><blockquote><para>I think a web-based message board clearly reads commands interactively. So, if there is such a notice, you can't remove it. But you could alter its form, so long as it is still appropriate.</para><para>-Dave Turner</para><para>Free Software Licensing Guru<indexterm><primary>Guru</primary></indexterm></para><para>This is not legal advice. If you need legal advice, see a lawyer.</para></blockquote><para>This pretty much says it all.</para></sect2>
</sect1>
<sect1 id="php-nuke-theme-modifying-icons"><title>Modifying the <application>PHP-Nuke</application> theme icons</title><para>You are not allowed to use PHP-Nuke's own icons (found in <ulink url="http://phpnuke.org/modules.php?name=Topics">phpnuke.org: Topics</ulink>). From the <ulink url="http://phpnuke.org/modules.php?name=FAQ&amp;myfaq=yes&amp;id_cat=1&amp;categories=PHP-Nuke+General+Info">PHP-Nuke FAQ</ulink>:</para><blockquote><para>Can I copy and use your topics graphics?<indexterm><primary>graphics</primary></indexterm></para><para>Absolutely No. All the topics graphics has been made by me and have copyright.<indexterm><primary>copyright</primary></indexterm> You can't copy, modify and/or use those graphics.<indexterm><primary>graphics</primary></indexterm> You can only use &quot;phpnuke.gif&quot; topic image to setup a topic in your web site that refers &quot;only&quot; to <application>PHP-Nuke</application>. Will be exceptions to this rule for <application>PHP-Nuke</application> community's sites. If you run a community support site (for <application>PHP-Nuke</application> ONLY), drop me line. You'll need my written permission to use them. Be fair and don't play with my hard work.</para></blockquote><para>Thus, you must use your own icons.<indexterm><primary>icons</primary></indexterm> You will have to either use icons that are royalty free, or licence some for use on your site, or create your own ones. </para><para>To create your own <application>PHP-Nuke</application> icons,<indexterm><primary>icons</primary></indexterm> you can use some of the tools available specifically for this purpose, e.g. <ulink url="http://www.nukeresources.com/modules.php?name=Downloads&amp;d_op=viewdownloaddetails&amp;lid=154&amp;ttitle=The_Topic_Dude">The Topic Dude</ulink>.</para></sect1>
<sect1 id="theme-rules"><title>Theme construction: the rules to follow </title><para>Considering that the example is always on NukeNews,<indexterm><primary>NukeNews</primary></indexterm> I suggest you always use this theme as an example, by using the HTML template without directly inserting too many tags in the <acronym>PHP</acronym> code, you save time and increase the sites stylistic effect by easily making changes across your site.</para><orderedlist><listitem><para>When you add images in an automatic way by using a visual editor,<indexterm><primary>editor</primary></indexterm> the path will be only images/image.gif, and you have to correct it by hand with the right path.</para></listitem><listitem><para>You can insert variables in the HTML that will then be called by <acronym>PHP</acronym> - it is important that they are inserted in the global part of the function<indexterm><primary>function</primary></indexterm> that will include the file.</para></listitem><listitem><para>The visual editor has the defect to open and close the tables,<indexterm><primary>tables</primary></indexterm> correcting what it thinks is an error. Pay attention because sometimes, in the html files we use, a table is not closed because it will be closed by the successive html file. For example, as often happened, DreamWeaver would close a header by making a mistake in the tables.<indexterm><primary>tables</primary></indexterm> The header must be closed in the following way:</para><screen><![CDATA[<td bgcolor="#ffffff "width="150" valign="top ">
]]></screen><para>Where this table is that one that includes the right blocks.</para></listitem><listitem><para>Try to <ulink url="http://www.karakas-online.de/myServices/w3c-html-validator.html">validate the HTML code</ulink> as much as possible and to use the style sheets (see <xref linkend="CSS-syntax">) as much you can. In this way you will save a lot of time when you will modify colors, fonts<indexterm><primary>fonts</primary></indexterm> etc.</para></listitem></orderedlist></sect1>
<sect1 id="change-buggy-php-nuke-theme"><title>How to change a buggy <application>PHP-Nuke</application> theme</title><para>You changed your <application>PHP-Nuke</application> theme to one that is buggy. Now, you cannot see anything, or you only see errors and the Administration panel cannot be reached to change the theme - a chicken-and-egg problem...<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_frown.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_frown.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_frown.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_frown.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject></para>
<para>There are various solutions to this problem:</para><orderedlist><listitem><para>Copy the following code into a file and save it as fixtheme.<indexterm><primary>theme</primary></indexterm>php: </para><screen><![CDATA[<?php
]]><![CDATA[require("config.php");
]]><![CDATA[$host = $dbhost;
]]><![CDATA[$database = $dbname;
]]><![CDATA[$username = $dbuname;
]]><![CDATA[$password = $dbpass;
]]><![CDATA[$def_theme = "NukeNews";
]]><![CDATA[mysql_connect($host, $username, $password);
]]><![CDATA[@mysql_select_db($database);
]]><![CDATA[mysql_query("update ".$prefix."_config set Default_Theme='$def_theme'");
]]><![CDATA[?>
]]></screen><para>If you don't have the NukeNews theme uploaded in your site then change the value for $def_theme in the code above so that it reflects one of your working themes,<indexterm><primary>themes</primary></indexterm> save it, upload it to where nuke's config.php file is, then point your browser to http://yoursite.com/fixtheme.<indexterm><primary>theme</primary></indexterm>php (thanks to <ulink url="http://www.humpa.com">Humpa</ulink> for this).</para></listitem><listitem><para>Just rename the DeepBlue theme (or some other theme known to work) folder to the problematic one.</para></listitem><listitem><para>Use phpMyAdmin and change the default_theme field in the nuke_config table.</para></listitem></orderedlist></sect1>
<sect1 id="prevent-users-from-changing-php-nuke-theme"><title>How to prevent users from changing the theme in PHP-Nuke</title><para>PHP-Nuke comes with several standard themes.<indexterm><primary>themes</primary></indexterm> It gives your registered users the possibility to change the theme at the click of a button (see <xref linkend="frontend">). But what if you don't want your users to do that? What if you want them to stay with the default theme you chose in the Preferences (see <xref linkend="administration-functions">) of the administration panel?<indexterm><primary>panel</primary></indexterm></para><para>There are two ways to achieve this (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=330">I do not want to let users choose their own themes</ulink>):</para><orderedlist><listitem><para>You delete all themes except the one chosen by you. Themes are stored in the themes folder, under directories that carry the theme name. <application>PHP-Nuke</application> counts the available themes in function nav() of the file modules/Your_Account/navbar.php:</para><screen><![CDATA[ $handle=opendir('themes');
]]><![CDATA[ while ($file = readdir($handle)) {
]]><![CDATA[ if ( (!ereg("[.]",$file)) ) {
]]><![CDATA[ $thmcount++;
]]><![CDATA[ }
]]><![CDATA[ }
]]><![CDATA[ closedir($handle);
]]></screen><para>If the theme count $thmcount is greater than 1 - and only then - , the registered user is presented the possibility to change the theme.<indexterm><primary>theme</primary></indexterm> This is done again in function nav() of modules/Your_Account/navbar.php a few lines further down:</para><screen><![CDATA[ if ($thmcount > 1) {
]]><![CDATA[ $menuimg = menuimg("themes.gif");
]]><![CDATA[ echo "<td width=\"10%\"><font class=\"content\">"
]]><![CDATA[ ."<center><a href=\"modules.php?name=Your_Account&amp;op=chgtheme\">
]]><![CDATA[ <img src=\"$menuimg\" border=\"0\" alt=\""
]]><![CDATA[ ._SELECTTHETHEME."\" title=\""._SELECTTHETHEME."\"></a><br>"
]]><![CDATA[ ."<a href=\"modules.php?name=Your_Account&amp;op=chgtheme\">"
]]><![CDATA[ ._SELECTTHETHEME."</a>"
]]><![CDATA[ ."</center></form></font></td>";
]]><![CDATA[ }
]]></screen><para>Thus, by deleting all other themes you will get a theme count of only 1 and the theme change functionality will not be available to the user.</para></listitem><listitem><para>Why get to all the trouble and delete whole theme directories? From what we said above, it should suffice just as well to replace the line</para><screen><![CDATA[if ($thmcount > 1) {
]]></screen><para>with </para><screen><![CDATA[if ($thmcount > 1000) {
]]></screen><para>Unless you really installed more than a thousand themes,<indexterm><primary>themes</primary></indexterm> your users are not going to get the chance to change the default one!</para></listitem></orderedlist><para>Choose the first solution, if you don't want to touch the code, choose the second one, if you are lazy. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
<warning>
<title>
Don't delete themes if you already have registered users!
</title>
<para>
Do the above changes before you go online and start getting registered users. Why? Because if you already have some, you don't know if the theme they chose in the User Preferences was the one you want to be the default. If it is not, and you apply either solution above, then those users will not be able to get into your site! Either the theme they specified will not be there, or they will not be able to change it.
</para>
<para>
The first solution has the extra disadvantage that if you choose to change the default theme, you will need to move it under the themes folder. Thus, even for a very short period of time, you will end up having two themes available. You never know if a user just chose the theme you wanted to remove as her default theme. That user will be denied access to your site the next time she tries, because the theme will not be there anymore!
</para>
<para>
In cases you do have registered users, you are thus advised to run the following SQL statement, either from the MySQL prompt, or through a graphical frontend, like phpMyAdmin:
</para>
<screen><![CDATA[update nuke_users set theme=";]]></screen>
<para>
This will set the theme to blank for all users, making it for them possible to change it to the default one afterwards, see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=14853">disabling themes</ulink> and also <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=18836">Where is the themeheader function located?</ulink>.
</para>
</warning>
</sect1>
<sect1 id="change-php-nuke-theme-depending-on-module"><title>How to change the <application>PHP-Nuke</application> theme depending on the module</title><para>For some web designs, it is desirable to always use the same theme for a few modules,<indexterm><primary>modules</primary></indexterm> while letting the user choose his own theme for the rest. Let's say you want to use the NukeNews theme for the News and Sections<indexterm><primary>Sections</primary></indexterm> modules, but let the user's personal theme be applied to the other modules<indexterm><primary>modules</primary></indexterm> of your site.</para><para>The theme is set in the get_theme function of mainfile.php.<indexterm><primary>mainfile.php</primary></indexterm> Thus, all you have to do is declare the $name variable to be global in that function,<indexterm><primary>function</primary></indexterm> then check its value before the selected theme is returned (i.e. immediately before the return statement) and, if it is, say &quot;News&quot;, or &quot;Sections&quot;<indexterm><primary>Sections</primary></indexterm>, to choose the NukeNews theme (see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=18245">Truly Global Variables</ulink>):</para><screen>
<![CDATA[function get_theme() {]]>
<![CDATA[ global $user, $cookie, $Default_Theme, $name;]]> <co id="gtname">
<![CDATA[ if(is_user($user)) {]]>
<![CDATA[ $user2 = base64_decode($user);]]>
<![CDATA[ $t_cookie = explode(":", $user2);]]>
<![CDATA[ if($t_cookie[9]=="") $t_cookie[9]=$Default_Theme;]]>
<![CDATA[ if(isset($theme)) $t_cookie[9]=$theme;]]>
<![CDATA[ if(!$tfile=@opendir("themes/$t_cookie[9]")) {]]>
<![CDATA[ $ThemeSel = $Default_Theme;]]>
<![CDATA[ } else { ]]>
<![CDATA[ $ThemeSel = $t_cookie[9];]]>
<![CDATA[ }]]>
<![CDATA[ } else {]]>
<![CDATA[ $ThemeSel = $Default_Theme;]]>
<![CDATA[ }]]>
<![CDATA[ if ($name == "News" || $name == "Sections") {]]> <co id="gtcheck">
<![CDATA[ $ThemeSel = "NukeNews";]]> <co id="gtsel">
<![CDATA[ } else {]]>
<![CDATA[ /* Don't change the theme */ ]]>
<![CDATA[ }]]>
<![CDATA[ return($ThemeSel);]]>
<![CDATA[}]]>
</screen>
<calloutlist>
<callout arearefs="gtname">
<para>
Declare $name to be global.
</para>
</callout>
<callout arearefs="gtcheck">
<para>
Check if the module name, $name, is News or Sections.
</para>
</callout>
<callout arearefs="gtsel">
<para>
Set the selected theme to NukeNews.
</para>
</callout>
</calloutlist>
<para>Of course, there is nothing magic about $name. You could take just any other variable and make the theme selection be dependent on it. You would only have to declare it global in the get_theme() function and in the modules that you would like to se t it. </para></sect1>
<sect1 id="change-font-size-php-nuke"><title>How to change the font size in PHP-Nuke</title><para>Since every theme comes with a CSS (style.css,<indexterm><primary>style.css</primary></indexterm> see also <xref linkend="CSS-syntax"> and <xref linkend="make-dynamic-CSS">) in the styles folder of the theme itself (see <xref linkend="topic-structure">), it is very easy to apply global formatting changes to our <application>PHP-Nuke</application> site: we just edit the CSS file. For example, to change the font size for all documents, we don't have to chase &lt;font&gt; tags in the <acronym>PHP</acronym> code - we only need to edit the style.css of our theme.<indexterm><primary>theme</primary></indexterm></para><note>
<title>&lt;/font&gt; is deprecated in HTML 4.x</title>
<para>
&lt;/font&gt; tags are deprecated in the HTML standard, starting from version 4.0, see <ulink url="http://www.w3.org/TR/REC-html40/present/graphics.html#h-15.2.2">Font modifier elements: FONT and BASEFONT</ulink>.
</para>
</note>
<para>Typically, in style.css there will be one or more lines specifying the font size, like:</para><screen><![CDATA[FONT {FONT-FAMILY: Verdana,Helvetica; FONT-SIZE: 11px}
]]><![CDATA[TD {FONT-FAMILY: Verdana,Helvetica; FONT-SIZE: 11px}
]]><![CDATA[BODY {FONT-FAMILY: Verdana,Helvetica; FONT-SIZE: 11px}
]]><![CDATA[P {FONT-FAMILY: Verdana,Helvetica; FONT-SIZE: 11px}
]]><![CDATA[DIV {FONT-FAMILY: Verdana,Helvetica; FONT-SIZE: 11px}
]]></screen><para>or </para><screen><![CDATA[.title {BACKGROUND: none; COLOR: #000000; FONT-SIZE: 13px;
]]><![CDATA[FONT-WEIGHT: bold; FONT-FAMILY: Verdana, Helvetica; TEXT-DECORATION: none}
]]><![CDATA[.content {BACKGROUND: none; COLOR: #000000; FONT-SIZE: 11px;
]]><![CDATA[FONT-FAMILY: Verdana, Helvetica}
]]><![CDATA[.storytitle {BACKGROUND: none; COLOR: #363636; FONT-SIZE: 14px;
]]><![CDATA[FONT-WEIGHT: bold; FONT-FAMILY: Verdana, Helvetica; TEXT-DECORATION: none}
]]></screen><para>Font size is usually specified in pixels (px), but other units are also possible (see <ulink url="http://www.bigbaer.com/css_tutorials/css_font_size.htm">CSS Font-Size</ulink>):</para><itemizedlist><listitem><para>Relative units - they specify a length relative to another length.</para><itemizedlist><listitem><para>em: the 'font-size' of the relevant font.</para></listitem><listitem><para>ex: the 'x-height' of the relevant font.</para></listitem><listitem><para>px: pixels,<indexterm><primary>pixels</primary></indexterm> relative to the viewing device.</para></listitem></itemizedlist><para>Thus, the 'em' unit is equal to the <emphasis>computed</emphasis> value of the 'font-size' property of the element on which it is used. The exception is when 'em' occurs in the value of the 'font-size' property itself, in which case it refers to the font size of the <emphasis>parent<indexterm><primary>parent</primary></indexterm></emphasis> element. That's what the following joke refers to:</para><para>What did one .em say to the other .em? <emphasis>Who's your Daddy?</emphasis> <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_smile.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_smile.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_smile.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_smile.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
</listitem><listitem><para>Absolute units:</para><itemizedlist><listitem><para>in: inches -- 1 inch is equal to 2.54 centimeters.<indexterm><primary>centimeters</primary></indexterm></para></listitem><listitem><para>cm: centimeters<indexterm><primary>centimeters</primary></indexterm></para></listitem><listitem><para>mm: millimeters<indexterm><primary>millimeters</primary></indexterm></para></listitem><listitem><para>pt: points -- the points used by CSS2 are equal to 1/72th of an inch.</para></listitem><listitem><para>pc: picas -- 1 pica is equal to 12 points.</para></listitem></itemizedlist></listitem></itemizedlist><para>Depending on where you make the font size change, it may apply only to the title,<indexterm><primary>title</primary></indexterm> the content or even the wholy body. Inheritance in the HTML document tree is applied by the browser to decide which properties can be passed on from the &ldquo;parent<indexterm><primary>parent</primary></indexterm>&rdquo; elements to the &ldquo;children&rdquo; or the &ldquo;descendants<indexterm><primary>descendants</primary></indexterm>&rdquo;. This is called &ldquo;cascading<indexterm><primary>cascading</primary></indexterm>&rdquo; and is responsible for the first &ldquo;C&rdquo; in &ldquo;CSS<indexterm><primary>CSS</primary></indexterm>&rdquo;. You need to understand cascading to use the full potential of CSS,<indexterm><primary>CSS</primary></indexterm> but for simple changes like this one, you can just experiment and get the idea (see <xref linkend="CSS-syntax"> for a short discussion of CSS syntax).</para><para>However, it is better, from the &quot;Accessibility&quot; point of view, to let your users decide themselves what font size they like, by setting it in up in their browsers (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=383">How to change font size</ulink>). Read <ulink url="http://diveintoaccessibility.org/day_26_using_relative_font_sizes.html">Using relative font sizes</ulink> for the background on this. Using the advice given in that article,<indexterm><primary>article</primary></indexterm> Chris has the following in the <ulink url="http://www.karakas-online.de/myLinuxTips/css-for-docbook.html">CSS file for DocBook</ulink> that controls the appearence of the <ulink url="http://www.karakas-online.de/EN-Book/">PHP-Nuke HOWTO</ulink> (and actually, all other documents on his site):</para><screen><![CDATA[P {
]]><![CDATA[ font-size: 12px;
]]><![CDATA[}
]]><![CDATA[/*/*/A{}
]]><![CDATA[BODY P {
]]><![CDATA[ font-size: x-small;
]]><![CDATA[ voice-family: "\"}\"";
]]><![CDATA[ voice-family: inherit;
]]><![CDATA[ font-size: small;
]]><![CDATA[}
]]><![CDATA[HTML>BODY P {
]]><![CDATA[ font-size: small;
]]><![CDATA[}
]]><![CDATA[/* */
]]></screen><para>There's a lot going on here, and it's all important, so pay attention (taken from <ulink url="http://diveintoaccessibility.org/day_26_using_relative_font_sizes.html">Using relative font sizes</ulink>):</para><orderedlist><listitem><para>First, we're defining an absolute size (12px) for every &lt;p&gt;. All browsers apply this style, including Netscape 4.</para></listitem><listitem><para>Then we include the odd-looking comment &quot;/*/*/&quot;. Due to bugs in Netscape 4, everything between this comment and the following one will be ignored. That's right, all the following styles will only be applied in non-Netscape-4<indexterm><primary>non-Netscape-4</primary></indexterm> browsers.</para></listitem><listitem><para>Immediately after the odd-looking comment, we include an empty rule &quot;a {}&quot;. Opera 5 for Mac is buggy and ignores this rule (and only this rule). It applies everything else.</para></listitem><listitem><para>We have now carved out a realm where we can define rules that are applied in all browsers except Netscape 4. Now we can start defining relative font sizes (which Netscape 4 can't handle). The first thing we do is use a &quot;body p&quot; selector to redefine the behaviour of the p tag. Due to the way CSS works, this will override our previous p selector.<indexterm><primary>selector</primary></indexterm> (In technical terms,<indexterm><primary>terms</primary></indexterm> &quot;body p&quot; is a more specific selector than &quot;p&quot;.)</para></listitem><listitem><para>We redefine the font size of all &lt;p&gt; tags to be x-small. This is a font size keyword which, at default settings, Internet Explorer<indexterm><primary>Explorer</primary></indexterm> 5 for <productname>Windows</productname> will translate into 12px.<indexterm><primary>12px</primary></indexterm> However, if the user changes their &quot;Text Size&quot; (under the View menu), this text will scale larger or smaller, depending on the user's setting. This is what we want. (Note: we've now defined font-size twice for IE5/Win, but that's okay, because the more specific selector always wins, and the previous selector<indexterm><primary>selector</primary></indexterm> is simply ignored.)</para></listitem><listitem><para>Unfortunately, IE5/Win an off-by-1 bug with its font size keywords;<indexterm><primary>words</primary></indexterm> every other browser in the world (IE5/Mac, Netscape 6, Mozilla,<indexterm><primary>Mozilla</primary></indexterm> IE6/Win) will translate x-small to 10px,<indexterm><primary>10px</primary></indexterm> not 12px. Luckily for us, IE5/Win has its own parsing bug that we can exploit:<indexterm><primary>exploit</primary></indexterm> it looks at that odd-looking voice-family and mistakenly thinks that this entire &quot;body p&quot; selector is over, so it ignores all the lines until the &quot;}&quot;.</para></listitem><listitem><para>Now we have carved out a smaller realm where we can define rules that are applied in all browsers except IE5/Win (and Netscape 4, which is still blissfully ignoring all of this). So we redefine font-size to small, which modern non-IE5/Win browsers (the only ones still listening) correctly interpret as 12px (at default settings). Again, if the user sets their &quot;text size&quot; to larger, this text will scale larger, which is what we want.</para></listitem><listitem><para>But wait! Opera 5 has the same parsing bug that IE5/Win has, so it was also confused by the voice-family hack,<indexterm><primary>hack</primary></indexterm> but it correctly interprets font size keywords,<indexterm><primary>words</primary></indexterm> so now our text will look too small in Opera 5. Luckily, Opera 5 supports a third type of selector,<indexterm><primary>selector</primary></indexterm> &quot;html&gt;body p&quot;. (Again, this is &quot;more specific&quot; than &quot;body p&quot;, so it takes precedence over the previous selector.<indexterm><primary>selector</primary></indexterm>) IE5/Win does not support this type of selector, so it will just ignore it, which is what we want (since we've already compensated for it's off-by-1 bug and don't want to go mucking that up now). IE6/Win also does not support it, but that's OK, because we caught it with the &quot;font-size:<indexterm><primary>font-size</primary></indexterm> small&quot; after the &quot;voice-family: inherit&quot; hack in the &quot;body p&quot; selector.<indexterm><primary>selector</primary></indexterm> All other browsers support &quot;html&gt;body&quot; selectors, so for them we end up defining font-size four times. Again, that's not a problem, because the most specific selector always wins, and the rest are simply ignored.</para></listitem><listitem><para>Finally, we have a set of empty comments:<indexterm><primary>comments</primary></indexterm> /* */. This triggers Netscape 4's parser to start listening again. If we defined any further rules after these empty comments,<indexterm><primary>comments</primary></indexterm> all browsers (including Netscape 4) would apply them.</para></listitem></orderedlist><para>To recap:</para><orderedlist><listitem><para>Netscape 4 displays &lt;p&gt; text at 12px,<indexterm><primary>12px</primary></indexterm> regardless of user setting.</para></listitem><listitem><para>Internet Explorer 5 for <productname>Windows</productname> displays &lt;p&gt; text at x-small, which works out to be 12px at the default setting, but would scale larger if the user set their &quot;Text Size&quot; setting larger in the View menu.<indexterm><primary>menu</primary></indexterm></para></listitem><listitem><para>Internet Explorer 6 for <productname>Windows</productname> displays &lt;p&gt; text at small, because of the &quot;font-size:<indexterm><primary>font-size</primary></indexterm> small&quot; rule in the &quot;body p&quot; selector. This works out to 12px at the default setting, but would scale larger if the user set their &quot;Text Size&quot; setting larger.</para></listitem><listitem><para>Internet Explorer 5 for Mac, Opera, Netscape 6, Mozilla,<indexterm><primary>Mozilla</primary></indexterm> and (hopefully) all future browsers will display &lt;p&gt; text at small, because of the &quot;font-size:<indexterm><primary>font-size</primary></indexterm> small&quot; rule in the &quot;html&gt;body p&quot; selector.<indexterm><primary>selector</primary></indexterm> This works out to 12px at the default setting, but would scale larger if the user used the &quot;Text Zoom&quot; feature.</para></listitem></orderedlist><tip>
<title>
Dive into Accessibility!
</title>
<para>
By the way, the whole <ulink url="http://diveintoaccessibility.org/table_of_contents.html">Dive into Accessibility</ulink> document by Mark Pilgrim is highly recommended reading for everyone. It will open your eays to a different world - that also uses the Internet!
</para>
</tip>
</sect1>
</chapter>
<chapter id="modifying-php-nuke-html-header"><title>Modifying the <application>PHP-Nuke</application> HTML header</title><para>The <application>PHP-Nuke</application> HTML header (i.e. everything that goes between the &lt;head&gt; and &lt;/head&gt; tags in the HTML code of the generated page) is fully customizable through the includes/my_header.<indexterm><primary>header</primary></indexterm>php file. This file contains whatever custom stuff you need to include in your site when the header loads.<indexterm><primary>ads</primary></indexterm> This can be used for third party banners,<indexterm><primary>banners</primary></indexterm> custom javascript, popup windows, etc. With this file you don't need to edit system code each time you upgrade to a new version. Just remember, in case you add code here to not overwrite this file when updating! Whatever you put here will be between &lt;head&gt; and &lt;/head&gt; tags.</para><para>Here are some example customizations of the <application>PHP-Nuke</application> HTML header:<indexterm><primary>header</primary></indexterm></para><sect1 id="favourites-icon-favicon-ico"><title>How to implement a favourites icon (favicon.ico)</title><para>Would you like to use a custom icon to appear in the URL address field at the top of the IE window when people are at your site? This is a &ldquo;favicon<indexterm><primary>favicon</primary></indexterm>&rdquo;, a favourites icon, that small icon that you see besides the URL when you visit some cool sites. This &ldquo;functionality<indexterm><primary>functionality</primary></indexterm>&rdquo; was introduced by the Internet Explorer.<indexterm><primary>Explorer</primary></indexterm> When you add a site to your Favourites list, Internet Explorer (version 5 and above) asks the server if it has a file called favicon.<indexterm><primary>favicon</primary></indexterm>ico. If present, this file will be used to provide an icon that is displayed next to the bookmark text. It is not visible in the old browsers, but newer ones, like Mozilla and Konqueror,<indexterm><primary>Konqueror</primary></indexterm> will also display it.</para><para>To display a favicon,<indexterm><primary>favicon</primary></indexterm> you have first to create one. The icon has to be in the ICO format which, contrary to common belief, is NOT the same as GIF, or PNG.<indexterm><primary>PNG</primary></indexterm> You have to transform your GIF or PNG file to ICO format.<indexterm><primary>format</primary></indexterm> For Windows,<indexterm><primary>Windows</primary></indexterm> you can use one of the numerous icon tools (<xref linkend="php-nuke-theme-modifying-icons">). For Linux,<indexterm><primary>Linux</primary></indexterm> simply create a 16x16 PNG file and convert it to an icon resource with <ulink url="http://www.winterdrache.de/freeware/png2ico">png2ico</ulink>. </para><para>Upload the ICO file to, say, images/favicon.<indexterm><primary>favicon</primary></indexterm>ico. Then add the following lines in the includes/my_header.<indexterm><primary>header</primary></indexterm>php file, somewhere between the &ldquo;&lt;?php&rdquo; and &ldquo;?&gt;&rdquo; tags:</para><screen><![CDATA[echo "<link rel=\"icon\" href=\"images/favicon.ico\" type=\"image/x-icon\">";
]]><![CDATA[echo ]]>&ldquo;<![CDATA[<link rel=\"shortcut icon\" href=\"images/favicon.ico\" type=\"image/x-icon\">]]>&rdquo;<![CDATA[;
]]></screen><note>
<title>
Note:
</title>
<para>
If you did the above and your browser still does not show the icon, remember that it may be using an old cache. Empty the cache and remember that even with a new cache, the browser may be using some old information, so you will have to be patient, or check it with a browser that did not visit that URL before.
</para>
</note>
<para>For more information on how to create and use a favicon,<indexterm><primary>favicon</primary></indexterm> see <ulink url="http://www.winterdrache.de/freeware/png2ico/favicon.html">How To Create And Install A favicon.ico</ulink>.</para></sect1>
<sect1 id="prevent-statistics-module-gathering-hits"><title>How to prevent the statistics module from gathering hits from certain hosts</title><para>If you are still in the phase of editing and tweaking your <application>PHP-Nuke</application> site while it is already online, you may find out that your frequent visits are counted just as every other visit to your site by the statistics module. During a very productive phase, this can skew the statistics of your site quite a bit! <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
<para>Contrary to what you might have expected, to prevent the statistics module<indexterm><primary>module</primary></indexterm> from gathering hits from certain hosts, like your own one, you have to edit the header.<indexterm><primary>header</primary></indexterm>php file, not any other file from the modules folder.</para><note>
<title>
header.php and includes/my_header.php
</title>
<para>
Do not confuse header.php, a file located in the <application>PHP-Nuke</application> root directory, with the my_header.php file, located under the includes directory. The former contains standard <application>PHP-Nuke</application> functions for the <application>PHP-Nuke</application> header, the latter is there for your own, personal additions to the header.
</para>
</note>
<para>In your header.<indexterm><primary>header</primary></indexterm>php file, find the code:</para><screen><![CDATA[include("includes/counter.php");
]]></screen><para>and replace it with<footnote><para>See <ulink url="http://www.nukeforums.com/forums/viewtopic.php?topic=12839&amp;forum=42">Block hosts from total hits in statistics module</ulink>.</para></footnote>:</para><screen><![CDATA[global $admin;
]]><![CDATA[if(!is_array($admin)) {
]]><![CDATA[$admin_name = base64_decode($admin);
]]><![CDATA[$admin_name = explode(":", $admin_name);
]]><![CDATA[$admin_name = "$admin_name[0]";
]]><![CDATA[} else {
]]><![CDATA[$admin_name = "$admin[0]";
]]><![CDATA[}
]]><![CDATA[if($admin_name != "PutYourAdminNameHere") {
]]><![CDATA[include("includes/counter.php");
]]><![CDATA[}
]]></screen><para>Put your administrator name in place of the "PutYourAdminNameHere" string in the above code and visits by that administrator will not increase your statistics counter any more. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_smile.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_smile.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_smile.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_smile.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
<tip>
<title>
How to block all administrators from the statistics counter
</title>
<para>
A simpler fix, which will block all administrators from the statistics counter, is:
</para>
<screen>
<![CDATA[global $admin;]]>
<![CDATA[if(!$admin)]]>
<![CDATA[{]]>
<![CDATA[inlude("includes/counter.php");]]>
<![CDATA[}]]>
</screen>
</tip>
</sect1>
</chapter>
<chapter id="modifying-mainfile-php"><title>Modifying mainfile.php</title><para>The mainfile.php file in the root directory of <application>PHP-Nuke</application> contains all commonly used functions and plays a crucial role in <application>PHP-Nuke</application>. We devote this chapter to a closer investigation of this central file. We show:</para><itemizedlist><listitem><para>How to allow special HTML tags (<xref linkend="allow-special-HTML-tags">).</para></listitem><listitem><para>How to change the order of messages (<xref linkend="change-order-of-messages">).</para></listitem></itemizedlist><warning>
<title>
Warning
</title>
<para>
Most of the changes discussed in this chapter have direct or indirect security implications (see <xref linkend="security">). No line in mainfile.php was put there without some reason, the reason being often security-related. Whenever you comment a line that seems to do a too restrictive check on user input, for example, bear in mind that in the worst of all cases you may run the risk of being hacked because of the absence of exactly a check like that.
</para>
</warning>
<sect1 id="allow-special-HTML-tags"><title>How to allow special HTML tags</title><para>User input is checked and filtered automatically by <application>PHP-Nuke</application>. For this purpose the functions filter_text and check_html are used. filter_text checks and replaces bad words, then calls check_html,<indexterm><primary>check_html</primary></indexterm> which in turn checks for HTML tags and strips them completely off, if the second parameter is &ldquo;nohtml<indexterm><primary>nohtml</primary></indexterm>&rdquo;.</para><para><xref linkend="tab-filter-text"> shows all modules that call filter_text,<indexterm><primary>filter_text</primary></indexterm> together with the line the call is made on. You can see that filter_text is used to filter<indexterm><primary>filter</primary></indexterm></para><itemizedlist><listitem><para>the text of a mail response in the WebMail module<indexterm><primary>module</primary></indexterm></para></listitem><listitem><para>the comments in the News module<indexterm><primary>module</primary></indexterm></para></listitem><listitem><para>the comments in the Reviews module<indexterm><primary>module</primary></indexterm></para></listitem><listitem><para>the subject,<indexterm><primary>subject</primary></indexterm> story and extended story text in the Submit_News module</para></listitem><listitem><para>the subject and comments in the Surveys module<indexterm><primary>module</primary></indexterm></para></listitem><listitem><para>the username and message in the Your_Account module<indexterm><primary>module</primary></indexterm></para></listitem></itemizedlist><para><table id="tab-filter-text"><title>Calls to filter_text from <application>PHP-Nuke</application> modules (v.6.8)</title><tgroup cols="2" colsep="1" rowsep="1">
<colspec colname="col0" align="left">
<colspec colname="col1" align="left">
<tbody>
<row>
<entry align="left" valign="top"><para>Module</para></entry>
<entry align="left" valign="top"><para>Line with call to filter_text</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/WebMail/readmail.php </para></entry>
<entry align="left" valign="top"><para>$res = filter_text($res); // Security fix by Ulf Harnhammar 2002</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/News/comments.php</para></entry>
<entry align="left" valign="top"><para>$comment = FixQuotes(nl2br(filter_text($comment)));</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/News/comments.php</para></entry>
<entry align="left" valign="top"><para>$subject = FixQuotes(filter_text($subject, &quot;nohtml&quot;));</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/News/comments.php</para></entry>
<entry align="left" valign="top"><para>$comment = FixQuotes(filter_text($comment));</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Reviews/index.php</para></entry>
<entry align="left" valign="top"><para>$comments = FixQuotes(nl2br(filter_text($comments)));</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Submit_News/index.php</para></entry>
<entry align="left" valign="top"><para>$subject = FixQuotes(filter_text($subject, &quot;nohtml&quot;));</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Submit_News/index.php</para></entry>
<entry align="left" valign="top"><para>$story = FixQuotes(nl2br(filter_text($story)));</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Submit_News/index.php</para></entry>
<entry align="left" valign="top"><para>$storyext = FixQuotes(nl2br(filter_text($storyext)));</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Submit_News/index.php</para></entry>
<entry align="left" valign="top"><para>$story = FixQuotes(filter_text($story));</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Submit_News/index.php</para></entry>
<entry align="left" valign="top"><para>$storyext = FixQuotes(filter_text($storyext));</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Surveys/comments.php</para></entry>
<entry align="left" valign="top"><para>$subject = FixQuotes(filter_text($subject, &quot;nohtml&quot;));</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Surveys/comments.php</para></entry>
<entry align="left" valign="top"><para>$comment = FixQuotes(nl2br(filter_text($comment)));</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Surveys/comments.php</para></entry>
<entry align="left" valign="top"><para>$comment = FixQuotes(filter_text($comment));</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Your_Account/index.php</para></entry>
<entry align="left" valign="top"><para>filter_text($username);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Your_Account/index.php</para></entry>
<entry align="left" valign="top"><para>if ($bio) { filter_text($bio); $bio = $EditedMessage; $bio = FixQuotes($bio); }</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Your_Account/index.php</para></entry>
<entry align="left" valign="top"><para>$the_message = FixQuotes(filter_text($the_message, &quot;nohtml&quot;));</para></entry>
</row>
</tbody>
</tgroup></table></para><para>check_html,<indexterm><primary>check_html</primary></indexterm> in turn, is not only called from filter_text, but also in its own right. <xref linkend="tab-check-html"> shows all modules that call check_html and the line it is called on. You can see that check_html is called to check the HTML input in</para><itemizedlist><listitem><para>the query string in the Downloads,<indexterm><primary>ads</primary></indexterm> Encyclopedia, Web Links and Search sections</para></listitem><listitem><para>the title,<indexterm><primary>title</primary></indexterm> text, reviewer, URL text and comments in the Reviews module</para></listitem><listitem><para>user name, e-mail,<indexterm><primary>e-mail</primary></indexterm> various user info fields in the Your Account module</para></listitem><listitem><para>bodytext and comments in the Journal module<indexterm><primary>module</primary></indexterm></para></listitem></itemizedlist><para><table id="tab-check-html"><title>Calls to check_html from <application>PHP-Nuke</application> modules (v.6.8)</title><tgroup cols="2" colsep="1" rowsep="1">
<colspec colname="col0" align="left">
<colspec colname="col1" align="left">
<tbody>
<row>
<entry align="left" valign="top"><para>Module</para></entry>
<entry align="left" valign="top"><para>Line with call to filter_text</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Downloads/index.php</para></entry>
<entry align="left" valign="top"><para>$query = check_html($query, nohtml);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Encyclopedia/search.php</para></entry>
<entry align="left" valign="top"><para>$query = check_html($query, nohtml);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Encyclopedia/search.php</para></entry>
<entry align="left" valign="top"><para>$query = check_html($query, nohtml);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Reviews/index.php</para></entry>
<entry align="left" valign="top"><para>$title = stripslashes(check_html($title, &quot;nohtml&quot;));</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Reviews/index.php</para></entry>
<entry align="left" valign="top"><para>$text = stripslashes(check_html($text, &quot;&quot;));</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Reviews/index.php</para></entry>
<entry align="left" valign="top"><para>$reviewer = stripslashes(check_html($reviewer, &quot;nohtml&quot;));</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Reviews/index.php</para></entry>
<entry align="left" valign="top"><para>$url_title = stripslashes(check_html($url_title, &quot;nohtml&quot;));</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Reviews/index.php</para></entry>
<entry align="left" valign="top"><para>$title = stripslashes(FixQuotes(check_html($title, &quot;nohtml&quot;)));</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Reviews/index.php</para></entry>
<entry align="left" valign="top"><para>$text = stripslashes(Fixquotes(urldecode(check_html($text, &quot;&quot;))));</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Reviews/index.php</para></entry>
<entry align="left" valign="top"><para>$comments = stripslashes(FixQuotes(check_html($comments)));</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Search/index.php</para></entry>
<entry align="left" valign="top"><para>$query = stripslashes(check_html($query, nohtml));</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Web_Links/index.php</para></entry>
<entry align="left" valign="top"><para>$query = check_html($query, nohtml);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Your_Account/index.php</para></entry>
<entry align="left" valign="top"><para>$username = check_html($username, nohtml);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Your_Account/index.php</para></entry>
<entry align="left" valign="top"><para>$user_email = check_html($user_email, nohtml);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Your_Account/index.php</para></entry>
<entry align="left" valign="top"><para>$user_email = check_html($user_email, nohtml);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Your_Account/index.php</para></entry>
<entry align="left" valign="top"><para>$femail = check_html($femail, nohtml);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Your_Account/index.php</para></entry>
<entry align="left" valign="top"><para>$user_website = check_html($user_website, nohtml);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Your_Account/index.php</para></entry>
<entry align="left" valign="top"><para>$bio = check_html($bio, nohtml);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Your_Account/index.php</para></entry>
<entry align="left" valign="top"><para>$user_avatar = check_html($user_avatar, nohtml);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Your_Account/index.php</para></entry>
<entry align="left" valign="top"><para>$user_icq = check_html($user_icq, nohtml);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Your_Account/index.php</para></entry>
<entry align="left" valign="top"><para>$user_aim = check_html($user_aim, nohtml);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Your_Account/index.php</para></entry>
<entry align="left" valign="top"><para>$user_yim = check_html($user_yim, nohtml);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Your_Account/index.php</para></entry>
<entry align="left" valign="top"><para>$user_msnm = check_html($user_msnm, nohtml);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Your_Account/index.php</para></entry>
<entry align="left" valign="top"><para>$user_occ = check_html($user_occ, nohtml);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Your_Account/index.php</para></entry>
<entry align="left" valign="top"><para>$user_from = check_html($user_from, nohtml);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Your_Account/index.php</para></entry>
<entry align="left" valign="top"><para>$user_interests = check_html($user_interests, nohtml);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Your_Account/index.php</para></entry>
<entry align="left" valign="top"><para>$realname = check_html($realname, nohtml);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Journal/display.php</para></entry>
<entry align="left" valign="top"><para>$row[bodytext]=check_html($row[bodytext], $strip);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>modules/Journal/display.php</para></entry>
<entry align="left" valign="top"><para>$row[comment]=check_html($row[comment], $strip);</para></entry>
</row>
</tbody>
</tgroup></table></para><para>check_html uses the $AllowableHTML array that is defined in config.php.<indexterm><primary>config.php</primary></indexterm> The idea is that only the tags that are included in the $AllowableHTML<indexterm><primary>AllowableHTML</primary></indexterm> array should be allowed. However, even if you explicitly allow the img tag in $AllowableHTML,<indexterm><primary>AllowableHTML</primary></indexterm> it will be stripped away by check_html (and by filter_text,<indexterm><primary>filter_text</primary></indexterm> which also calls it). The line that does this is </para><screen><![CDATA[$str = eregi_replace("<[[:space:]]* img[[:space:]]*([^>]*)[[:space:]]*>", ", $str);
]]></screen><para>You can comment out that line - though it is certainly a security issue (allowing people to post harmful code in img tags). </para><para>You can also comment out the line that eliminates all anchor attributes<indexterm><primary>attributes</primary></indexterm> exept href in the &lt;a&gt; tag:</para><screen><![CDATA[$str = eregi_replace("<a[^>]*href[[:space:]]*=[[:space:]]*\"?[[:space:]]*([^\" >]*)[[:space:]]*\"?[^>]*>", '<a href="\\1">', $str); # "
]]></screen><para>These changes will affect the checks done at all places shown in both <xref linkend="tab-filter-text"> and <xref linkend="tab-check-html">, so again, be careful with security issues. You have to trust your users to give them this comfort.</para><para>Put the tags you want to allow in the $AllowableHTML array in the config.php<indexterm><primary>config.php</primary></indexterm> file. Here is a (quite liberal) example:</para><screen><![CDATA[$AllowableHTML = array("b"=>1,
]]><![CDATA[ "i"=>1,
]]><![CDATA[ "a"=>2,
]]><![CDATA[ "em"=>1,
]]><![CDATA[ "br"=>1,
]]><![CDATA[ "strong"=>1,
]]><![CDATA[ "blockquote"=>1,
]]><![CDATA[ "tt"=>1,
]]><![CDATA[ "li"=>1,
]]><![CDATA[ "ol"=>1,
]]><![CDATA[ "H1"=>1,
]]><![CDATA[ "H2"=>1,
]]><![CDATA[ "H3"=>1,
]]><![CDATA[ "H4"=>1,
]]><![CDATA[ "center"=>1,
]]><![CDATA[ "img"=>2,
]]><![CDATA[ "alt"=>1,
]]><![CDATA[ "table"=>2,
]]><![CDATA[ "tr"=>2,
]]><![CDATA[ "td"=>2,
]]><![CDATA[ "p"=>2,
]]><![CDATA[ "div"=>2,
]]><![CDATA[ "font"=>2,
]]><![CDATA[ "p"=>1,
]]><![CDATA[ "p"=>1,
]]><![CDATA[ "ul"=>1);
]]></screen><para>The numbers that appear next to each tag have the following meaning:</para><itemizedlist><listitem><para>a 1 means the tag does not accept any attributes<indexterm><primary>attributes</primary></indexterm></para></listitem><listitem><para>a 2 indicates that the tag may also contain attributes<indexterm><primary>attributes</primary></indexterm></para></listitem></itemizedlist><para>See also <xref linkend="config-php-file">.</para></sect1>
<sect1 id="change-order-of-messages"><title>How to change the order of messages</title><para>
<figure id="fig-messages-2">
<title>
Administration panel: Messages.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1133;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1133;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1133;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1133;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Messages.</phrase>
</textobject>
<caption>
<para>Administration panel: Messages.</para>
</caption>
</mediaobject>
</figure>
</para><para>The default for <application>PHP-Nuke</application> is to display messages in ascending order of mid<indexterm><primary>mid</primary></indexterm> (the id number for each message). You can use Add Story (<xref linkend="fig-stories">) to post articles on your site and these will appear in reverse order, i.e. last posted at the top (see also <xref linkend="order-articles-in-sections">, on how to order articles in Sections and <xref linkend="order-articles-in-stories-archive">, on how to order articles in the Stories Archive). Thus you could have a main &ldquo;Welcome Message&rdquo; at the top which will always be there as a home page, followed by a series<indexterm><primary>series</primary></indexterm> of announcements appearing in reverse order below the Welcome Message. But what happens if you don't use &ldquo;Add Story&rdquo; to add articles, but would rather like to use Messages (<xref linkend="fig-messages">) for communicating your news?<indexterm><primary>news</primary></indexterm></para><para>If you really want to use Messages and have them appear in reverse order (last one at the top), you need to edit mainfile.php using a decent editor<indexterm><primary>editor</primary></indexterm> (see <xref linkend="editing-PHP-Nuke-files">).</para><para>At around line 334 in mainfile.php,<indexterm><primary>mainfile.php</primary></indexterm> in function message_box(), change</para><screen><![CDATA[$sql = "SELECT mid, title, content, date, expire, view
]]><![CDATA[FROM ".$prefix."_message WHERE active='1' $querylang";
]]></screen><para>to</para><screen><![CDATA[$sql = "SELECT mid, title, content, date, expire, view
]]><![CDATA[FROM ".$prefix."_message WHERE active='1' $querylang ORDER by mid DESC";
]]></screen><para>and this will display your messages in reverse order (last one at the top). See also <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=339">How to reverse the order of Messages in the Homepage</ulink>.</para></sect1>
<sect1 id="change-duration-of-public-broadcast-message"><title>How to change the duration of a public broadcast message</title><para>So you want the public broadcast message to show for a longer/shorter period? There is a simple solution (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=126">How to change the duration of a public broadcast message</ulink>):</para><para>You can increase the time the message will be displayed by editing the following lines in mainfile.php:<indexterm><primary>mainfile.php</primary></indexterm></para><screen><![CDATA[$ref_date = $tdate+600;
]]></screen><para>and </para><screen><![CDATA[setcookie("p_msg",$mid,time()+600);
]]></screen><para>Adjust the 600 to a value that matches the time you want the message displayed.</para></sect1>
</chapter>
<chapter id="modifying-php-nuke-blocks"><title>Modifying <application>PHP-Nuke</application> blocks</title><para>In this chapter we show how to <emphasis>modify</emphasis> <application>PHP-Nuke</application> blocks. If you are interested in <emphasis>creating</emphasis> <application>PHP-Nuke</application> blocks, read <xref linkend="block-creation">. We cover the topics:<indexterm><primary>topics</primary></indexterm></para><itemizedlist><listitem><para>How to change a buggy block (<xref linkend="change-buggy-block">),</para></listitem><listitem><para>How to build custom module blocks (<xref linkend="build-custom-module-blocks">),</para></listitem><listitem><para>How to build RSS blocks with variable number of news items (<xref linkend="build-rss-blocks-with-variable-news-number">),</para></listitem><listitem><para>How to get scrolling headlines in blocks (<xref linkend="scrolling-headlines-in-blocks">).</para></listitem></itemizedlist><sect1 id="change-buggy-block"><title>How to change a buggy block</title><para>You activated a buggy <application>PHP-Nuke</application> block. Now, your site is broken and you get a blank page, or you only see errors and the administration panel is unreachable because the block breaks your page's design...<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_frown.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_frown.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_frown.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_frown.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject></para>
<para>There is a very simple solution to this very annoying problem (see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=17559">Site crashed when block was created</ulink>): just replace the broken block,<indexterm><primary>block</primary></indexterm> say block-Broken.php, with a script that does not contain anything but the following line:</para><screen><![CDATA[<?php $content=""; ?>
]]></screen><para>Then, the administration panel should be reachable and you can deactivate<indexterm><primary>activate</primary></indexterm> the offending block.<indexterm><primary>block</primary></indexterm></para></sect1>
<sect1 id="build-custom-module-blocks"><title>How to build custom module blocks</title><para>
<figure id="fig-modules-block">
<title>
The standard Modules block
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1134;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1134;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1134;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1134;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase> The standard Modules block</phrase>
</textobject>
<caption>
<para> The standard Modules block</para>
</caption>
</mediaobject>
</figure>
</para><para>A module block is a block that displays links to all available modules of a <application>PHP-Nuke</application> site (<xref linkend="fig-modules-block">). It is the block that appears at the top of the left column, with the standard title &ldquo;Modules<indexterm><primary>Modules</primary></indexterm>&rdquo;. The module block is a standard <application>PHP-Nuke</application> block,<indexterm><primary>block</primary></indexterm> for its construction you have to follow the same rules as for any other block (see <xref linkend="block-creation">). It is thus fairly easy to construct your own module block,<indexterm><primary>block</primary></indexterm> if you are not satisfied with the standard one. Below are some examples:</para><itemizedlist><listitem><para>Simple module block (<xref linkend="simple-module-block">),</para></listitem><listitem><para>Treemenu block (<xref linkend="treemenu-block">).</para></listitem></itemizedlist><sect2 id="simple-module-block"><title>Simple module block</title><para>The links that are inside the standard <application>PHP-Nuke</application> module block are constructed dynamically, using information that is available about the modules in the database.<indexterm><primary>base</primary></indexterm> For example, to present only active modules in the links, the block (located in blocks/block-Modules.<indexterm><primary>Modules</primary></indexterm>php) checks the &ldquo;active&rdquo; field of the $prefix_modules table (which is table nuke_modules,<indexterm><primary>modules</primary></indexterm> if $prefix is left to the standard &ldquo;nuke&rdquo; in config.php,<indexterm><primary>config.php</primary></indexterm> see <xref linkend="config-php-file">):</para><screen><![CDATA[$sql = "SELECT title, custom_title FROM ".$prefix."_modules
]]><![CDATA[WHERE active='1' AND inmenu='0' ORDER BY title ASC";
]]></screen><para>As we can easily read in the SELECT query above, only modules with the &ldquo;active&rdquo; bit set to 1 are selected. But we also see that the order in which they are selected is the standard ascending lexicographic order of the modules' title (ORDER BY title ASC). If we wish a different ordering, we are left with only a few possibilities:</para><itemizedlist><listitem><para>Change the order from ascending (ASC) to descending (DESC):</para><screen><![CDATA[$sql = "SELECT title, custom_title FROM ".$prefix."_modules
]]><![CDATA[WHERE active='1' AND inmenu='0' ORDER BY title DESC";
]]></screen></listitem><listitem><para>Change the field on which the ORDER BY clause is applied, e.g. use custom_title instead of title:<indexterm><primary>title</primary></indexterm></para><screen><![CDATA[$sql = "SELECT title, custom_title FROM ".$prefix."_modules
]]><![CDATA[WHERE active='1' AND inmenu='0' ORDER BY custom_title ASC";
]]></screen></listitem><listitem><para>Add an extra field to the $prefix_modules table, populate it with custom<indexterm><primary>custom</primary></indexterm> values (e.g. &ldquo;1&rdquo; for the module we want to be the first in the list, , &ldquo;2&rdquo; for the second, &ldquo;3&rdquo; for the third etc. if we decided to use a numeric field ) for each module, and sort in ascending<indexterm><primary>ascending</primary></indexterm> order of this new field:</para><screen><![CDATA[$sql = "SELECT title, custom_title FROM ".$prefix."_modules
]]><![CDATA[WHERE active='1' AND inmenu='0' ORDER BY new_field ASC";
]]></screen></listitem></itemizedlist><para>But if we wish a custom grouping of the modules links, we will have to write our own modules block.<indexterm><primary>block</primary></indexterm> You can use the following code as a starting point for your own creations.<indexterm><primary>ations</primary></indexterm> This script will display certain links only when an admin or user is logged in. Just name it block-menuSample.php and put in the blocks folder, deactivate<indexterm><primary>activate</primary></indexterm> the block-Modules.<indexterm><primary>Modules</primary></indexterm>php and activate this one (see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=10792">Different links - some for registered users only</ulink> and <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=14816">How would I add a clickable link in a Modules Block?</ulink>):</para><screen><![CDATA[<?php
]]><![CDATA[if (eregi("block-menuSample.php",$PHP_SELF)) {
]]><![CDATA[Header("Location: index.php");
]]><![CDATA[die();
]]><![CDATA[}
]]><![CDATA[Global $user, $admin;
]]><![CDATA[$title = "Main Menu";
]]><![CDATA[$content = "
]]><![CDATA[<font size=\"1\" face=\"Verdana, Arial, Helvetica, sans-serif\">
]]><![CDATA[<B><u>Navigation</u>
]]><![CDATA[<BR>
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<a href=index.php>Start Page</a><br><br>
]]><![CDATA[<u>Information</u><BR>
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=News&file=index\">News</A><BR>
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=aboutus\">About us</A><BR>
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=somefolder&file=index\">Entry with Some word</A><BR>
]]><![CDATA[<BR>
]]><![CDATA[<u>Other things</u>
]]><![CDATA[<BR>
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=Web_Links
]]><![CDATA[&amp;file=index&amp;l_op=viewlink&amp;cid=1\">Links</A><BR>
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=My_eGallery\">All sorts of Pictures</A><br>
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=Reviews\">Reviews</A><BR>
]]><![CDATA[<BR>
]]><![CDATA[<u>Interact</u>
]]><![CDATA[<BR>
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=GuestBook\">Guestbook</A><BR>
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=Feedback\">Feedback</A><BR>
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=Recommend_Us\">Recommend Us</A><BR>
]]><![CDATA[<BR>
]]><![CDATA[<u>Misc.</u>
]]><![CDATA[<BR>
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=Web_Links\">Links</A><BR>
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=FAQ\">FAQ</A><BR>
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=Web_Links
]]><![CDATA[&amp;file=index&amp;l_op=AddLink\">Add A Link</A><BR>
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=Downloads\">Downloads</A><BR>
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=Statistics\">Site Statistics</A><BR>
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=HeadLines\">News Headlines</A><BR>
]]><![CDATA[<BR>
]]><![CDATA[//******************************************
]]><![CDATA[//Below is for users and admins ONLY!!!
]]><![CDATA[//******************************************
]]><![CDATA[<u>User Control Panel</u>
]]><![CDATA[<BR>";
]]><![CDATA[if (!IsSet($user))
]]><![CDATA[{;
]]><![CDATA[$content .= "
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=Your_Account\">Reg. Users Login. </A><br>";
]]><![CDATA[}
]]><![CDATA[if ((IsSet($user)) or (IsSet($admin)))
]]><![CDATA[{;
]]><![CDATA[$content .= "
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=Your_Account\">Your Account</A><BR>
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=Your_Account&amp;op=edituser\">Edit Profile</A><BR>
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=Members_Photo_Upload\">Members Photo upload</A><BR>
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=Members_List\">View Member List</A><BR>
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=Your_Account&amp;op=logout\">logout</A><BR>
]]><![CDATA[<BR>
]]><![CDATA[<u>Private Messages</u>
]]><![CDATA[<BR>
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=Private_Messages\">View Messages</A><BR>
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=Private_Messages
]]><![CDATA[&amp;file=reply&amp;send=1\">Compose A Message</A><BR>
]]><![CDATA[";
]]><![CDATA[};
]]><![CDATA[//***************************************
]]><![CDATA[//ENDS HERE
]]><![CDATA[//***************************************
]]><![CDATA[$content .= "
]]><![CDATA[<BR>
]]><![CDATA[<u>Send Content</u>
]]><![CDATA[<BR>
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=Submit_News\">Submit News</A><BR>
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=Reviews&amp;rop=write\">Write A Review</A><BR>
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=Web_Links
]]><![CDATA[&amp;file=index&amp;l_op=AddLink\">Add A Link</A><BR>
]]><![CDATA[<STRONG><BIG><3E></BIG></STRONG>
]]><![CDATA[<A href=\"modules.php?name=My_eGallery
]]><![CDATA[&amp;file=index&amp;do=upload\">Add images to the Gallery</A><BR>
]]><![CDATA[<BR>
]]><![CDATA[</font>
]]><![CDATA[</B>
]]><![CDATA[<HR size=3>
]]><![CDATA[";
]]><![CDATA[?>
]]></screen></sect2>
<sect2 id="treemenu-block"><title>Treemenu block</title><para>A commonly asked question in <ulink url="http://phpnuke.org">PHPNuke</ulink> forums (see for example <ulink url="http://www.nukeforums.com/forums/viewtopic.php?mode=viewtopic&amp;t=11926">Menu Hack Needed (show different menu or block depending on the category)</ulink>), is if there exists some Module block out there that displays a dynamic<indexterm><primary>dynamic</primary></indexterm> view of the available modules.<indexterm><primary>modules</primary></indexterm> The webmaster needs a functionality that will allow for the display of only certain module links, depending on, say, the interests, access level,<indexterm><primary>access level</primary></indexterm> or preferences of the viewer. </para><para>A typical Module block,<indexterm><primary>block</primary></indexterm> as shipped with the standard PHPNuke package, looks as in <xref linkend="fig-modules-block-2">.</para><para>
<figure id="fig-modules-block-2">
<title>
The standard Modules block.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1135;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1135;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1135;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1135;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase> The standard Modules block.</phrase>
</textobject>
<caption>
<para> The standard Modules block.</para>
</caption>
</mediaobject>
</figure>
</para><para>What we need instead is a module block that displays some links (to modules,<indexterm><primary>modules</primary></indexterm> or generally, to pages) when a certain condition is met (say, when <ulink url="http://www.karakas-online.de/EN-Book/preinstalled-modules.html">Category</ulink> A was previously chosen) and some other ones when a different condition<indexterm><primary>condition</primary></indexterm> is true (e.g. when Category B was chosen).</para><sect3 id="general-idea"><title>The general idea </title><para>To met the above requirements,<indexterm><primary>requirements</primary></indexterm> the <ulink url="http://www.karakas-online.de/myTreemenu/">Treemenu block for PHP-Nuke</ulink> adapts the well-known <ulink url="http://www.bitbuddha.com/php/treemenu/">Treemenu</ulink> concept to a PHPNuke Block and creates a PHPNuke block containing a Treemenu<indexterm><primary>menu</primary></indexterm> which looks as in <xref linkend="fig-treemenu">.</para><para>
<figure id="fig-treemenu">
<title>
Treemenu Block.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1136;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1136;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1136;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1136;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Treemenu Block.</phrase>
</textobject>
<caption>
<para>Treemenu Block.</para>
</caption>
</mediaobject>
</figure>
</para><para>When the user clicks on an item like &ldquo;Links&rdquo;, the subtree under this item is unfolded (<xref linkend="fig-treemenu1">).</para><para>
<figure id="fig-treemenu1">
<title>
Treemenu Block with &ldquo;Links&rdquo; expanded.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1137;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1137;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1137;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1137;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Treemenu Block with &ldquo;Links&rdquo; expanded.</phrase>
</textobject>
<caption>
<para>Treemenu Block with &ldquo;Links&rdquo; expanded.</para>
</caption>
</mediaobject>
</figure>
</para><para>A further click on the subcategory &ldquo;My work&rdquo; will reveal another level of groups (<xref linkend="fig-treemenu2">).</para><para>
<figure id="fig-treemenu2">
<title>
Treemenu Block with &ldquo;My work&rdquo; expanded.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1138;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1138;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1138;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1138;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Treemenu Block with &ldquo;My work&rdquo; expanded.</phrase>
</textobject>
<caption>
<para>Treemenu Block with &ldquo;My work&rdquo; expanded.</para>
</caption>
</mediaobject>
</figure>
</para><para>Finally, a click on a subsubcategory like &ldquo;Linux<indexterm><primary>Linux</primary></indexterm>&rdquo; will unfold the &ldquo;leaves<indexterm><primary>leaves</primary></indexterm>&rdquo; of the Treemenu (<xref linkend="fig-treemenu3">).</para><para>
<figure id="fig-treemenu3">
<title>
Treemenu Block with &ldquo;Linux&rdquo; expanded.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1139;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1139;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1139;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1139;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Treemenu Block with &ldquo;Linux&rdquo; expanded.</phrase>
</textobject>
<caption>
<para>Treemenu Block with &ldquo;Linux&rdquo; expanded.</para>
</caption>
</mediaobject>
</figure>
</para><para>Of course, the naming and nesting of categories and/or items is fully arbitrary. The above functionality can easily be adapted to suit more advanced needs too (see <ulink url="http://www.karakas-online.de/myTreemenu/refinements.html">refinements of the <application>PHP-Nuke</application> Treemenu</ulink>).</para></sect3>
<sect3 id="what-is-Treemenu"><title>What is Treemenu </title><para>The Treemenu block makes use of a Treemenu in a PHPNuke Block.<indexterm><primary>lock</primary></indexterm> Treemenu is a <acronym>PHP</acronym> class created by Bjorge Dijkstra (original script to be found <ulink url="http://www.hotscripts.com/Detailed/3704.html">Treemenu Class from Bjorge</ulink>) and adapted by Denny Shimkoski (his version to be found in <ulink url="http://www.bitbuddha.com/php/treemenu/">Treemenu from Denny</ulink>). Chris have fixed some bugs in the latter one and integrated it into a <ulink url="http://www.karakas-online.de/phpnuke/block-Treemenu.tgz">Treemenu block for PHP-Nuke</ulink>.</para><para>There are two ways you can use the Treemenu class - Chris uses the one that takes as input a <ulink url="./sitemap.txt">simple text file</ulink> and creates a tree menu,<indexterm><primary>menu</primary></indexterm> in a style that most users are familiar with from a graphical file manager (see <xref linkend="fig-treemenu">). Navigation through such a tree is done intuitively by expanding and collapsing<indexterm><primary>collapsing</primary></indexterm> the various tree levels by clicking on the node icons (the icons are discussed in <ulink url="http://www.karakas-online.de/myTreemenu/refinements.html">custom node icons for the <application>PHP-Nuke</application> Treemenu</ulink>).</para><para>To create a Treemenu,<indexterm><primary>menu</primary></indexterm> once you have written the input text file with your favorite text editor (see <ulink url="http://www.karakas-online.de/myTreemenu/what-is-treemenu.html#INPUT-FILE-METHOD">input file method for the Treemenu</ulink>) or used the <ulink url="http://www.karakas-online.de/myTreemenu/what-is-treemenu.html#ALTERNATIVE-METHOD">alternative method to fill the nodes and leaves of the Treemenu</ulink>, you just have to write this 3-liner to get it up and running:</para><screen><![CDATA[include("blocks/treemenu/treemenu.inc");
]]><![CDATA[$tree = new TreeMenu("a", "blocks/treemenu/sitemap.txt");
]]><![CDATA[$tree->show();
]]></screen><note>
<title>
Note
</title>
<para>
In order to be able to display the output of the above code in a PHPNuke Block, we have to capture it in an output buffer with the ob_start(), ob_get_contents() and ob_end_clean() mechanism:
<screen><![CDATA[ob_start();
]]><![CDATA[include("blocks/treemenu/treemenu.inc");
]]><![CDATA[$tree = new TreeMenu("a", "blocks/treemenu/sitemap.txt");
]]><![CDATA[$tree->show();
]]><![CDATA[$output = ob_get_contents();
]]><![CDATA[ob_end_clean();
]]><![CDATA[$content = $output;
]]></screen></para>
</note>
<para>See <ulink url="http://www.karakas-online.de/myTreemenu/">Treemenu block for PHP-Nuke</ulink> for more information of how to use the Treemenu block as a module block<indexterm><primary>block</primary></indexterm> for <application>PHP-Nuke</application>.</para></sect3>
</sect2>
</sect1>
<sect1 id="build-rss-blocks-with-variable-news-number"><title>How to build RSS blocks with variable number of news items</title><para>If you have created an RSS block from the block administration fuction of the administration panel,<indexterm><primary>panel</primary></indexterm> you may have noticed that, notably after some change on a previously working RSS block (for example, in the title,<indexterm><primary>title</primary></indexterm> or the refresh time), or even from the very start, you get the error:</para><screen><![CDATA[Currently there is a problem with headlines from this site
]]></screen><para>This is not always due to some error on your part - it is a bug too. Often, the only solution would be to delete the block and add it anew. </para><para>The problem is in the file admin/modules/blocks.php. There, the problematic code is</para><screen><![CDATA[for ($i=0;$i<10;$i++) {
]]><![CDATA[ $link = ereg_replace(".*<link>","",$items[$i]);
]]><![CDATA[ $link = ereg_replace("</link>.*","",$link);
]]><![CDATA[ $title2 = ereg_replace(".*<title>","",$items[$i]);
]]><![CDATA[ $title2 = ereg_replace("</title>.*","",$title2);
]]><![CDATA[ if ($items[$i] == "" AND $cont != 1) {
]]><![CDATA[ $content = "";
]]><![CDATA[ } else {
]]><![CDATA[ if (strcmp($link,$title2) AND $items[$i] != "") {
]]><![CDATA[ $cont = 1;
]]><![CDATA[ $content .= "<strong><big>&middot;</big></strong>&nbsp;<a href=\"$link\" target=\"new\">$title2</a><br>\n";
]]><![CDATA[ }
]]><![CDATA[ }
]]><![CDATA[}
]]></screen><para>which has the number of news items (10) hardcoded into it. The problem is caused by the fact that, if there aren't that many headlines<indexterm><primary>headlines</primary></indexterm> being returned, and in many unlucky cases, there aren't, you will either get an array out of bounds error, or nothing will be returned, and the content of the block will be set to equal nothing. </para><para>You could fix that by changing the &ldquo;10&rdquo; in the code above to &ldquo;5&rdquo;, for example. However, that fix wouldn't work for a site that had only three headlines<indexterm><primary>headlines</primary></indexterm> in their RSS file. What needs to happen is to modify the </para><screen><![CDATA[ $content = "";
]]><![CDATA[to
]]><![CDATA[ $content += "";
]]></screen><para>For a modification of the mainfile.php and admin/modules/blocks.php files that also allows for a variable number of items to be chosen from the administration panel individually for each RSS block,<indexterm><primary>block</primary></indexterm> see <ulink url="http://www.nickpadley.com/modules.php?name=Downloads&amp;d_op=getit&amp;li d=17">Digital Nick Downloads</ulink>, for a discussion thread on this bug,<indexterm><primary>bug</primary></indexterm> see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=13495">Problems when saving RSS block</ulink>.</para></sect1>
<sect1 id="scrolling-headlines-in-blocks"><title>How to get scrolling headlines in blocks</title><para>You may have noticed those scrolling headlines in blocks of some sites. Perhaps you abhor them, because they distract you from reading the context,<indexterm><primary>context</primary></indexterm> or because the scrolling effect is not supported by all browsers. But if you are fascinated by this effect and wondering how to achieve it in your own <application>PHP-Nuke</application> RSS blocks, here's how:</para><para>In mainfile.php,<indexterm><primary>mainfile.php</primary></indexterm> find the code for the headlines() function:</para><screen><![CDATA[function headlines($bid, $cenbox=0)
]]></screen><para>There, near the end, replace the lines</para><screen><![CDATA[if ($cenbox == 0) {
]]><![CDATA[ themesidebox($title, $content);
]]><![CDATA[} else {
]]><![CDATA[ themecenterbox($title, $content);
]]><![CDATA[}
]]></screen><para>with the lines</para><screen><![CDATA[if ($cenbox == 0) {
]]><![CDATA[ $content = "<marquee scrollamount=\"2\" direction=\"up\"
]]><![CDATA[ loop=\"true\">$content</marquee>";
]]><![CDATA[ themesidebox($title, $content);
]]><![CDATA[} else {
]]><![CDATA[ $content = "<marquee scrollamount=\"2\" direction=\"up\"
]]><![CDATA[ loop=\"true\">$content</marquee>";
]]><![CDATA[ themecenterbox($title, $content);
]]><![CDATA[}
]]></screen><para>Enclosing the old $content variable in the marquee code and assigning it to the $content variable again before the call to the themesidebox or themecenterbox functions, gives the desired scrolling effect for our RSS headlines.<indexterm><primary>headlines</primary></indexterm></para></sect1>
</chapter>
<chapter id="modifying-php-nuke-modules"><title>Modifying <application>PHP-Nuke</application> modules</title><para>
<figure id="fig-modules-5">
<title>
Administration panel: Modules.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1140;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1140;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1140;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1140;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Modules.</phrase>
</textobject>
<caption>
<para>Administration panel: Modules.</para>
</caption>
</mediaobject>
</figure>
</para><para>In this chapter we will talk about <emphasis>modifying</emphasis> <application>PHP-Nuke</application> modules.<indexterm><primary>modules</primary></indexterm> If you are interested in creating <application>PHP-Nuke</application> modules,<indexterm><primary>modules</primary></indexterm> read <xref linkend="creating-modules">. We will talk about:</para><itemizedlist><listitem><para>Modifying any <application>PHP-Nuke</application> module (<xref linkend="modifying-any-PHP-Nuke-module">),</para></listitem><listitem><para>Modifying the <application>PHP-Nuke</application> Homepage (<xref linkend="modifying-php-nuke-homepage">),</para></listitem><listitem><para>Modifying the <application>PHP-Nuke</application> FAQ module (<xref linkend="modifying-php-nuke-module-faq">),</para></listitem><listitem><para>Modifying the <application>PHP-Nuke</application> Reviews module (<xref linkend="modifying-php-nuke-module-reviews">),</para></listitem><listitem><para>Modifying the <application>PHP-Nuke</application> Web_Links module (<xref linkend="modifying-php-nuke-module-web-links">),</para></listitem><listitem><para>Modifying the <application>PHP-Nuke</application> Your_Account module (<xref linkend="modifying-php-nuke-moduke-your-account">),</para></listitem><listitem><para>Modifying the <application>PHP-Nuke</application> News module (<xref linkend="modifying-PHP-Nuke-News-module">),</para></listitem><listitem><para>Modifying the <application>PHP-Nuke</application> Submit News module (<xref linkend="modifying-PHP-Nuke-submit-news-module">),</para></listitem><listitem><para>Modifying the <application>PHP-Nuke</application> Sections module (<xref linkend="modifying-PHP-Nuke-sections-module">),</para></listitem><listitem><para>Modifying the <application>PHP-Nuke</application> Downloads module (<xref linkend="modifying-PHP-Nuke-downloads-module">),</para></listitem><listitem><para>Modifying the <application>PHP-Nuke</application> Stories Archive module (<xref linkend="modifying-PHP-Nuke-stories-archive">).</para></listitem></itemizedlist><sect1 id="modifying-any-PHP-Nuke-module"><title>Modifying any <application>PHP-Nuke</application> module</title><para>Talking about modifying any <application>PHP-Nuke</application> module in general, we will show:</para><itemizedlist><listitem><para>How to hide the right blocks (<xref linkend="hide-right-blocks">),</para></listitem><listitem><para>How to change a buggy module (<xref linkend="change-buggy-module">).</para></listitem></itemizedlist><sect2 id="hide-right-blocks"><title>How to hide the right blocks</title><para>If your module needs more space than is available in the central column of the <application>PHP-Nuke</application> layout,<indexterm><primary>layout</primary></indexterm> you may want to hide the right column of blocks. This is accomplished very easily from within the code of any module:<indexterm><primary>module</primary></indexterm> find the line </para><screen><![CDATA[$index = 1;
]]></screen><para>and change it to:</para><screen><![CDATA[$index = 0; // 0 : do not show right blocks - 1:show right blocks
]]></screen><para>Of course, if the line is not there, then $index is already 0, so your module already hides the right blocks.<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
<tip>
<title>
How to hide the left blocks
</title>
<para>
If you want to hide the left blocks, you have to modify the theme header. See <xref linkend="hide-left-blocks">.
</para>
</tip>
</sect2>
<sect2 id="change-buggy-module"><title>How to change a buggy module</title><para>You activated a buggy <application>PHP-Nuke</application> module. Now, your site is broken and you get a blank page, or you only see errors and the administration panel is unreachable...<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_frown.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_frown.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_frown.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_frown.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject></para>
<para>Connect to the MySQL database and change the value of the &quot;active&quot; field in the $prefix_modules table to 0 for that module's entry. Example (see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=17559">Site crashed when block was created</ulink> and <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=375">logout-Fehler</ulink>): suppose the broken module is Mod_Broken,<indexterm><primary>Mod_Broken</primary></indexterm> your $prefix is &quot;nuke&quot; and the value of the module id, &quot;mid&quot;<indexterm><primary>mid</primary></indexterm>, field for the Mod_Broken module is &quot;7&quot;):</para><screen><![CDATA[UPDATE nuke_modules SET active = '0' WHERE mid = '7';
]]></screen><para>or (if you prefer to select by title and not by module id)</para><screen><![CDATA[UPDATE nuke_modules SET active = '0' WHERE title = 'Mod_Broken';
]]></screen></sect2>
</sect1>
<sect1 id="modifying-php-nuke-homepage"><title>Modifying the <application>PHP-Nuke</application> Homepage</title><para>The <application>PHP-Nuke</application> Homepage is the &ldquo;Home&rdquo; module.<indexterm><primary>module</primary></indexterm> The Home module is chosen in the modules administration panel.<indexterm><primary>panel</primary></indexterm> We show:</para><itemizedlist><listitem><para>How to redirect users to the Login page (<xref linkend="redirect-users-to-login-page">),</para></listitem><listitem><para>How to restrict the Homepage only to registered users (<xref linkend="restrict-homepage-to-registered-users">).</para></listitem></itemizedlist><sect2 id="redirect-users-to-login-page"><title>How to redirect users to the Login page</title><para>If you want your users to be redirected straight to the Login page, rather than the Homepage, do the following:</para><para>Right at the begining of the index.<indexterm><primary>index</primary></indexterm>php file , add this code after the 'require_once(&ldquo;mainfile.php<indexterm><primary>mainfile.php</primary></indexterm>&rdquo;);' line, like this:</para><screen><![CDATA[require_once("mainfile.php");
]]><![CDATA[global $user;
]]><![CDATA[if(!is_user($user)) {
]]><![CDATA[ header("Location: modules.php?name=Your_Account");
]]><![CDATA[}
]]></screen><para>This will send anyone who is not logged in (or registered) to the Your Account (Login) page. See <xref linkend="redirect-users-to-homepage"> for the inverse procedure &mdash; but don't try both. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
<para>See <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=82">how to redirect from forms in a <application>PHP-Nuke</application> block</ulink> for redirection from other places, like blocks.</para></sect2>
<sect2 id="restrict-homepage-to-registered-users"><title>How to restrict the Homepage only to registered users</title><para>Suppose that you have set up the News module as the &ldquo;Homepage module<indexterm><primary>module</primary></indexterm>&rdquo; of your PHP-Nuke, but you want the news articles to be visible only to registered users. Can this be done?</para><para>Well, not exactly. Since you want the News module to be visible only to registered users, you cannot have it in the &quot;Home&quot;. This means you must put a different module in Home (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=377">hide articles from logged out users</ulink>). You can do this from the &quot;Put in Home&quot; link in the modules table shown in the modules administration panel (<xref linkend="administration-functions">, <xref linkend="fig-modules-admin">).</para><para>Once the News module is not in Home anymore, you can edit it and choose that it be visible only by the registered users.</para><note>
<para>
The "Who can View This?" selection box is not available, as long as the module remains the "Home" module of your P HP-Nuke installation. That's why you can't restrict the visibility of the Home module, no matter which module this is. T he reason for this is that it makes little sense to have a Home module and restrict its availability only to registered users, unless you want your site to be generally available only to registered members.
</para>
</note>
</sect2>
</sect1>
<sect1 id="modifying-php-nuke-module-faq"><title>Modifying the <application>PHP-Nuke</application> FAQ module</title><para>
<figure id="fig-faq-3">
<title>
Administration panel: FAQ.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1141;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1141;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1141;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1141;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: FAQ.</phrase>
</textobject>
<caption>
<para>Administration panel: FAQ.</para>
</caption>
</mediaobject>
</figure>
</para><para>In this section we modify the <application>PHP-Nuke</application> FAQ module:<indexterm><primary>module</primary></indexterm></para><itemizedlist><listitem><para>How to add more than 127 FAQ answers (<xref linkend="more-than-127-faq-answers">).</para></listitem></itemizedlist><sect2 id="more-than-127-faq-answers"><title>How to add more than 127 FAQ answers</title><para>You have 127 Q&amp;A. You cannot add more, if you delete one, you can add one.</para><para>Cause: Looking at the sql/nuke.sql script that creates the <application>PHP-Nuke</application> tables on installation,<indexterm><primary>installation</primary></indexterm> we see the following for the structure of the nuke_faqAnswer table:</para><screen><![CDATA[#
]]><![CDATA[# Table structure for table `nuke_faqAnswer`
]]><![CDATA[#
]]><![CDATA[
]]><![CDATA[CREATE TABLE nuke_faqAnswer (
]]><![CDATA[ id tinyint(4) NOT NULL auto_increment,
]]><![CDATA[ id_cat tinyint(4) NOT NULL default '0',
]]><![CDATA[ question varchar(255) default ",
]]><![CDATA[ answer text,
]]><![CDATA[ PRIMARY KEY (id),
]]><![CDATA[ KEY id (id),
]]><![CDATA[ KEY id_cat (id_cat)
]]><![CDATA[) TYPE=MyISAM;
]]></screen><para>From the <ulink url="http://www.mysql.com/doc/en/Column_types.html">MySQL manual on column types</ulink>, we see:</para><blockquote><para>TINYINT[(M)] [UNSIGNED] [ZEROFILL]</para><para>A very small integer.<indexterm><primary>integer</primary></indexterm> The signed range is -128 to 127.<indexterm><primary>127</primary></indexterm> The unsigned range is 0 to 255.</para></blockquote><para>so that tinyint is a very small integer indeed in this case.<indexterm><primary>case</primary></indexterm></para><para>Solution: Change the length of id and id_cat of nuke_faqAnswer.<indexterm><primary>nuke_faqAnswer</primary></indexterm> You can do this with phpMyAdmin,<indexterm><primary>Admin</primary></indexterm> or by logging into MySQL from the console and, after choosing the <application>PHP-Nuke</application> database (&quot;use xxxx;&quot;), by typing:</para><screen><![CDATA[alter table nuke_faqAnswer modify id SMALLINT unsigned;
]]><![CDATA[alter table nuke_faqAnswer modify id_cat SMALLINT unsigned;
]]></screen><para>See also <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=13841">FAQ problem</ulink>.</para></sect2>
</sect1>
<sect1 id="modifying-php-nuke-module-reviews"><title>Modifying the <application>PHP-Nuke</application> Reviews module</title><para>
<figure id="fig-reviews-2">
<title>
Administration panel: Reviews.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1142;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1142;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1142;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1142;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Reviews.</phrase>
</textobject>
<caption>
<para>Administration panel: Reviews.</para>
</caption>
</mediaobject>
</figure>
</para><para>In this section we modify the <application>PHP-Nuke</application> Reviews module:<indexterm><primary>module</primary></indexterm></para><itemizedlist><listitem><para>How to allow only registered users to enter a review (<xref linkend="allow-only-registered-users-to-review">),</para></listitem><listitem><para>How to choose images from a dropdown list (<xref linkend="choose-images-from-dropdown-list">).</para></listitem></itemizedlist><sect2 id="allow-only-registered-users-to-review"><title>How to allow only registered users to enter a review</title><para>If you want only your registered users to be able to enter a review, you can achieve it with the following simple change:</para><para>Edit the modules/Reviews/index.<indexterm><primary>index</primary></indexterm>php file and find the write_review() function:</para><screen><![CDATA[function write_review() {
]]><![CDATA[ global $admin, $sitename, $user, $cookie, $prefix, $user_prefix,
]]><![CDATA[ $currentlang, $multilingual, $dbi, $module_name;
]]><![CDATA[ include ('header.php');
]]><![CDATA[ OpenTable();
]]></screen><para>Add the following check after the call to OpenTable():</para><screen><![CDATA[ if (!is_user($user)) {
]]><![CDATA[ echo "You need to be
]]><![CDATA[ <a href=\"modules.php?name=Your_Account\">logged in</a> or
]]><![CDATA[ <a href=\"modules.php?name=Your_Account&op=new_user\">become a member</a>
]]><![CDATA[ to submit reviews.";
]]><![CDATA[ } else {
]]></screen><para>This check will only allow registered users to continue with a review, while pointing others to the login or register page. Of course, the IF statement has to be closed - just put a } at the end of the function,<indexterm><primary>function</primary></indexterm> as shown below:</para><screen><![CDATA[ CloseTable();
]]><![CDATA[ include ("footer.php");
]]><![CDATA[}
]]><![CDATA[}
]]></screen><para>Unregistered users will be able to view reviews,<indexterm><primary>reviews</primary></indexterm> but only site members will be able to submit new ones.</para><tip>
<title>
Tip
</title>
<para>
This simple check can be used to restrict access to registered users in any module that does not offer this functionality, not only in Reviews.
</para>
</tip>
</sect2>
<sect2 id="choose-images-from-dropdown-list"><title>How to choose images from a dropdown list</title><para>Isn't it more comfortable being able to choose the image for your review (if you are an administrator) from a dropdown list that offers the names of all available images in your image directory, rather than having to enter the full URL to the image each time? You could easily incorporate this functionality if you just cut and pasted the code from the admin/modules/topics.php file. The functionality is in the Topics module already - you don't need to write full URLs to the topics icons, do you?<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
<para>The relevant part in the Reviews to introduce the code from the Topics module<indexterm><primary>module</primary></indexterm> is the following code in modules/Reviews/index.php:<indexterm><primary>index.php</primary></indexterm></para><screen><![CDATA[ if(is_admin($admin)) {
]]><![CDATA[ echo "
]]><![CDATA[ <b>"._RIMAGEFILE.":</b><br>
]]><![CDATA[ <input type=\"text\" name=\"cover\" size=\"40\" maxlength=\"100\"><br>
]]><![CDATA[ <i>"._RIMAGEFILEREQ."</i><br><br>
]]><![CDATA[ ";
]]><![CDATA[ }
]]><![CDATA[Replace it with:
]]><![CDATA[ if(is_admin($admin)) {
]]><![CDATA[ echo "
]]><![CDATA[ <b>"._RIMAGEFILE.":</b><br>
]]><![CDATA[
]]><![CDATA[ echo "<select name="cover">";
]]><![CDATA[ $path1 = explode ("/", "images/reviews/");
]]><![CDATA[ $path = "$path1[0]/$path1[1]";
]]><![CDATA[ $handle=opendir($path);
]]><![CDATA[ while ($file = readdir($handle)) {
]]><![CDATA[ if ( (ereg("^([_0-9a-zA-Z]+)([.]{1})([_0-9a-zA-Z]{3})$",$file))
]]><![CDATA[ AND $file != "AllTopics.gif") {
]]><![CDATA[ $tlist .= "$file ";
]]><![CDATA[ }
]]><![CDATA[ }
]]><![CDATA[ closedir($handle);
]]><![CDATA[ $tlist = explode(" ", $tlist);
]]><![CDATA[ sort($tlist);
]]><![CDATA[ for ($i=0; $i < sizeof($tlist); $i++) {
]]><![CDATA[ if($tlist[$i]!="") {
]]><![CDATA[ if ($topicimage == $tlist[$i]) {
]]><![CDATA[ $sel = "selected";
]]><![CDATA[ } else {
]]><![CDATA[ $sel = "";
]]><![CDATA[ }
]]><![CDATA[ echo "<option name="cover" value="$tlist[$i]" $sel>$tlist[$i]n";
]]><![CDATA[ }
]]><![CDATA[ }
]]><![CDATA[ echo "</select><br>";
]]><![CDATA[
]]><![CDATA[ echo "<i>"._RIMAGEFILEREQ."</i><br><br>
]]><![CDATA[ ";
]]><![CDATA[ }
]]></screen><para>The part of code that was stolen from the Topics module (from the admin/modules/topics.<indexterm><primary>topics</primary></indexterm>php file) is between the blank lines in the above code. It will offer you a dropdown list of all images in the images/reviews folder. Just like with the topics images,<indexterm><primary>images</primary></indexterm> you must use all small letters and no underscores or other special characters. See <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=12983">choose image for review</ulink>.</para></sect2>
</sect1>
<sect1 id="modifying-php-nuke-module-web-links"><title>Modifying the <application>PHP-Nuke</application> Web_Links module</title><para>
<figure id="fig-weblinks-4">
<title>
Administration panel: Web Links.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1143;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1143;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1143;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1143;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Web Links.</phrase>
</textobject>
<caption>
<para>Administration panel: Web Links.</para>
</caption>
</mediaobject>
</figure>
</para><para>In this section we modify the <application>PHP-Nuke</application> Web Links module:<indexterm><primary>module</primary></indexterm></para><itemizedlist><listitem><para>How to display Web Links in the same window (<xref linkend="display-web-links-in-the-same-window">),</para></listitem><listitem><para>How to change the number of Web Links per page (<xref linkend="change-number-of-web-links-per-page">).</para></listitem></itemizedlist><sect2 id="display-web-links-in-the-same-window"><title>How to display Web Links in the same window</title><para>The Web_Links module will display each web link in a separate window. To change this behaviour and make it display the link in the same window, you have to change each occurence of </para><screen><![CDATA[target=\"new\"
]]></screen><para>to</para><screen><![CDATA[target=\"_self\"
]]></screen><para>in the modules/Web_Links/index.<indexterm><primary>index</primary></indexterm>php file. This is a straightforward search and replace procedure.<indexterm><primary>procedure</primary></indexterm> In vi, you would do</para><screen><![CDATA[1,$s/target=\\"new\\"/target=\\"_self\\"/g
]]></screen></sect2>
<sect2 id="change-number-of-web-links-per-page"><title>How to change the number of Web Links per page</title><para>You can change the number of Web Links that are displayed per page very easily - no programming necessary! <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_smile.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_smile.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_smile.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_smile.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
<para>Just change the value of $perpage in modules/Web_Links/l_config.php:<indexterm><primary>l_config.php</primary></indexterm></para><screen><![CDATA[$perpage = 10;
]]></screen><tip>
<title>
Make use of the module configuration files!
</title>
<para>
It definitely pays off to have a look at the configuration files of the various modules! The l_config.php file, for example, located in the Web_Links folder under the modules directory, offers many variables that can be used to achieve the desired appearence of the Web Links module:
</para>
<itemizedlist>
<listitem><para>$perpage: How many links to show on each page?</para></listitem>
<listitem><para>$popular: How many hits need a link to be listed as popular?</para></listitem>
<listitem><para>$newlinks: How many links to display in the New Links Page?</para></listitem>
<listitem><para>$toplinks: How many links to display in The Best Links Page? (Most Popular)</para></listitem>
<listitem><para>$linksresults: How many links to display on each search result page?</para></listitem>
<listitem><para>$links_anonaddlinklock: Lock Unregistered users from Suggesting New Links? (0=Yes 1=No)</para></listitem>
<listitem><para>$anonwaitdays: Number of days anonymous users need to wait to vote on a link</para></listitem>
<listitem><para>$outsidewaitdays: Number of days outside users need to wait to vote on a link (checks IP)</para></listitem>
<listitem><para>$useoutsidevoting: Allow Webmasters to put vote links on their site (1=Yes 0=No)</para></listitem>
<listitem><para>$anonweight: How many Unregistered User vote per 1 Registered User Vote?</para></listitem>
<listitem><para>$outsideweight: How many Outside User vote per 1 Registered User Vote?</para></listitem>
<listitem><para>$detailvotedecimal: Let Detailed Vote Summary Decimal out to N places. (no max)</para></listitem>
<listitem><para>$mainvotedecimal: Let Main Vote Summary Decimal show out to N places. (max 4)</para></listitem>
<listitem><para>$toplinkspercentrigger: 1 to Show Top Links as a Percentage (else # of links)</para></listitem>
<listitem><para>$toplinks: Either # of links OR percentage to show (percentage as whole number. #/100)</para></listitem>
<listitem><para>$mostpoplinkspercentrigger: 1 to Show Most Popular Links as a Percentage (else # of links)</para></listitem>
<listitem><para>$mostpoplinks: Either # of links OR percentage to show (percentage as whole number. #/100)</para></listitem>
<listitem><para>$featurebox: 1 to Show Feature Link Box on links Main Page? (1=Yes 0=No)</para></listitem>
<listitem><para>$linkvotemin: Number votes needed to make the 'top 10' list</para></listitem>
<listitem><para>$blockunregmodify: Block unregistered users from suggesting links changes? (1=Yes 0=No)</para></listitem>
</itemizedlist>
</tip>
</sect2>
</sect1>
<sect1 id="modifying-php-nuke-moduke-your-account"><title>Modifying the <application>PHP-Nuke</application> Your_Account module</title><para>In this section we modify the <application>PHP-Nuke</application> Your Account module,<indexterm><primary>module</primary></indexterm> one of the most central modules of <application>PHP-Nuke</application>. We show:</para><itemizedlist><listitem><para>How to redirect users to the Homepage (<xref linkend="redirect-users-to-homepage">),</para></listitem><listitem><para>How to redirect Your Info to the Forums user profile (<xref linkend="redirect-your-info-to-forums-user-profile">),</para></listitem><listitem><para>How to redirect users to Login and back (<xref linkend="redirect-users-to-login-and-back">),</para></listitem><listitem><para>How to disable registration (<xref linkend="disable-registration">),</para></listitem><listitem><para>How to let users register immediately (<xref linkend="register-users-immediately">),</para></listitem><listitem><para>How to approve users before registration (<xref linkend="approve-users">),</para></listitem><listitem><para>How to register users through iBill (<xref linkend="register-users-through-iBill">),</para></listitem><listitem><para>How to change the maximum allowed length for user names (<xref linkend="change-maximum-username-length">).</para></listitem></itemizedlist><sect2 id="redirect-users-to-homepage"><title>How to redirect users to the Homepage</title><para>Are you looking for a way to redirect a user to Home rather than Your Account<indexterm><primary>Your Account</primary></indexterm> when they login?<indexterm><primary>login</primary></indexterm> Would you rather prefer them to go to Your Account only when they choose to and be automatically redirected to Home when they login?<indexterm><primary>login</primary></indexterm> There is a simple way to accomplish this (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=333">How to redirect users to the Homepage</ulink> and <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=13776">Redirect login to home</ulink>):</para><para>Find the following lines in function login() in the modules/Your_Account/index.<indexterm><primary>index</primary></indexterm>php:</para><screen><![CDATA[Header("Location: modules.php?name=Your_Account&op=userinfo&bypass=1&username=$username");
]]></screen><para>Change it to this:</para><screen><![CDATA[Header("Location: index.php");
]]></screen><para>See <xref linkend="redirect-users-to-login-page"> for the inverse procedure &mdash; but don't try both. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
</sect2>
<sect2 id="redirect-your-info-to-forums-user-profile"><title>How to redirect Your Info to the Forums user profile</title><para>
<figure id="fig-your-info-profile-link">
<title>
Your Info link in the User Preferences panel.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1144;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1144;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1144;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1144;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Your Info link in the User Preferences panel.</phrase>
</textobject>
<caption>
<para>Your Info link in the User Preferences panel.</para>
</caption>
</mediaobject>
</figure>
</para><para>With the advent of <ulink url="http://www.phpbb.com">phpBB</ulink> forums in <application>PHP-Nuke</application> (starting from somewhere around v. 6.5), you not only have to cope with two administration panels, one for <application>PHP-Nuke</application> in general and one for the Forums in particular, your users can maintain their profile in two places too, from the Your Info link in the User Preference panel (<xref linkend="fig-your-info-profile-link">), as well as the Forums profile link in the Forums module (<xref linkend="fig-forum-profile-link">).</para><para>
<figure id="fig-forum-profile-link">
<title>
Forum Profile link in the Forums module.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1145;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1145;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1145;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1145;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Forum Profile link in the Forums module.</phrase>
</textobject>
<caption>
<para>Forum Profile link in the Forums module.</para>
</caption>
</mediaobject>
</figure>
</para><para>The Your Info link has the URL<indexterm><primary>URL</primary></indexterm></para><screen><![CDATA[modules.php?name=Your_Account&op=edituser
]]></screen><para>and leads to a panel similar to the one of <xref linkend="fig-your-info-profile">.</para><para>
<figure id="fig-your-info-profile">
<title>
User profile in Your Info.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1146;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1146;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1146;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1146;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>User profile in Your Info.</phrase>
</textobject>
<caption>
<para>User profile in Your Info.</para>
</caption>
</mediaobject>
</figure>
</para><para>The Profile link in the Forums module, on the other hand, has the URL<indexterm><primary>URL</primary></indexterm></para><screen><![CDATA[modules.php?name=Forums&file=profile&mode=editprofile
]]></screen><para>(optionally with the session <acronym>ID</acronym> parameter, sid,<indexterm><primary>sid</primary></indexterm> which is not shown here) and leads to the panel shown in <xref linkend="fig-forum-profile">.</para><para>Both panels use the same database tables in the background,<indexterm><primary>background</primary></indexterm> so it doesn't matter which one you use. This may be confortable for some, but also confusing for other users.</para><para>If your users find it confusing to use two different entry points for their personal information,<indexterm><primary>information</primary></indexterm> you can modify the Your_Account module to redirect them to the Forum profile (<xref linkend="fig-forum-profile">), even when they click on the Your Info link (<xref linkend="fig-your-info-profile-link">).</para><para>
<figure id="fig-forum-profile">
<title>
User profile in the Forums.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1147;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1147;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1147;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1147;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>User profile in the Forums.</phrase>
</textobject>
<caption>
<para>User profile in the Forums.</para>
</caption>
</mediaobject>
</figure>
</para><para>The Your Info link is output (&ldquo;echoed&rdquo;) in modules/Your_Account/navbar.php, in the following code block:<indexterm><primary>block</primary></indexterm></para><screen><![CDATA[echo "<font class=\"content\">"
]]><![CDATA[ ."<center><a href=\"modules.php?name=Your_Account&amp;op=edituser\">
]]><![CDATA[ <img src=\"$menuimg\" border=\"0\" alt=\""._CHANGEYOURINFO.
]]><![CDATA[ "\" title=\""._CHANGEYOURINFO."\"></a><br>"
]]><![CDATA[ ."<a href=\"modules.php?name=Your_Account&amp;op=edituser\">"
]]><![CDATA[ ._CHANGEYOURINFO."</a>"
]]><![CDATA[ ."</center></font></td>";
]]></screen><para>To redirect the users to the Forum profile (<xref linkend="fig-forum-profile">), you can change the above block to:</para><screen><![CDATA[echo "<font class=\"content\">"
]]><![CDATA[ ."<center><a href=\"modules.php?name=Forums&amp;file=profile&amp;mode=editprofile\">
]]><![CDATA[ <img src=\"$menuimg\" border=\"0\" alt=\""._CHANGEYOURINFO.
]]><![CDATA[ "\" title=\""._CHANGEYOURINFO."\"></a><br>"
]]><![CDATA[ ."<a href=\"modules.php?name=Forums&amp;file=profile&amp;mode=editprofile\">"
]]><![CDATA[ ._CHANGEYOURINFO."</a>"
]]><![CDATA[ ."</center></font></td>";
]]></screen><para>As you can easily see, we have changed only the two links (one for the image and one for the text), the other lines are for your reference only. </para><note>
<para>
It is not necessary to compute the user's numeric <acronym>ID</acronym> and pass it on the URL through the u parameter - the mode=editprofile parameter on the URL will find the user automatically (but mode=viewprofile will not!).
</para>
</note>
<para>But wait a minute! Is this really all we have to change? Is the Your Info link (<xref linkend="fig-your-info-profile-link">) the only one that leads a user to the profile screen of the Your_Info<indexterm><primary>Your_Info</primary></indexterm> module (<xref linkend="fig-your-info-profile">)? How about the user name links in other modules,<indexterm><primary>modules</primary></indexterm> for example? Search for the string &ldquo;op=edituser<indexterm><primary>edituser</primary></indexterm>&rdquo; and you will already find a ton of those links in various places (Newsletter,<indexterm><primary>Newsletter</primary></indexterm> language files, Reviews.<indexterm><primary>Reviews</primary></indexterm>..) And how about a new user? Will the new user registration screen be the one of Your_Account or the one of Forums?</para><para>Instead of chasing links in the code, there is a more elegant solution that will eliminate any attempt to bring a user to the Your Info profile at its very beginning! It is also a very good example of what type of control<indexterm><primary>control</primary></indexterm> you can achieve over your PHP-Nuke, if you put your knowledge about the way a module works (see <xref linkend="creating-modules">) into practice:</para><para>In modules/Your_Account/index.<indexterm><primary>index</primary></indexterm>php find the lines:</para><screen><![CDATA[case "edituser":
]]><![CDATA[edituser();
]]><![CDATA[break;
]]></screen><para>and replace them with:</para><screen><![CDATA[case "edituser":
]]><![CDATA[Header("Refresh: 0; url=modules.php?name=Forums&file=profile&mode=editprofile");
]]><![CDATA[break;
]]></screen><para>This will take care of the &ldquo;edit user&rdquo; case.<indexterm><primary>case</primary></indexterm> We need to do the same for the &ldquo;new user&rdquo; case too. Just replace</para><screen><![CDATA[case "new_user":
]]><![CDATA[new_user();
]]><![CDATA[break;
]]></screen><para>with:</para><screen><![CDATA[case "new_user":
]]><![CDATA[Header("Refresh: 0; url=modules.php?name=Forums&file=profile&mode=register");
]]><![CDATA[break;
]]></screen><para>The idea here is the following: instead of searching all code of all modules<indexterm><primary>modules</primary></indexterm> for links that point to the Your Info profile,<indexterm><primary>profile</primary></indexterm> we look at the parameters that such a link passes on the URL.<indexterm><primary>URL</primary></indexterm> A typical Your Info profile link is of the form:</para><screen><![CDATA[modules.php?name=Your_Account&op=edituser
]]></screen><para>so the parameters it passes to the modules.<indexterm><primary>modules</primary></indexterm>php script are:</para><itemizedlist><listitem><para>name: the name of the module to execute (Your_Account)</para></listitem><listitem><para>op: the operation to execute (edituser)</para></listitem></itemizedlist><para>The second URL parameter,<indexterm><primary>parameter</primary></indexterm> op, is checked at one single place in the code, in the switch statement of modules/Your_Account/index.php:<indexterm><primary>index.php</primary></indexterm></para><screen><![CDATA[switch($op) {
]]><![CDATA[ case "logout":
]]><![CDATA[ logout();
]]><![CDATA[ break;
]]><![CDATA[
]]><![CDATA[ ...many other cases checked here, among them "edituser" and "new_user"
]]><![CDATA[
]]><![CDATA[ default:
]]><![CDATA[ main($user);
]]><![CDATA[ break;
]]><![CDATA[}
]]></screen><para>This is the one and only point of control for the actions taken by the Your_Account module. We make use of this fact and change the actions that are to be taken for the operations "edituser" and "new_user". We don't change the links, we change the actions that follow when the links are clicked.<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_cool.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_cool.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_cool.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_cool.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject></para>
<para>This will make the Your Info profile practically inaccessible in your system<indexterm><primary>system</primary></indexterm> and will present the Forums profile instead.</para><warning>
<title>
Missing functionality in the Forums profile!
</title>
<para>
Bear in mind that, depending on the versions of <application>PHP-Nuke</application> and Forums, you may be missing some functionality in the Forums profile, that was present in the profile that was accessible through the Your Info link. This may include changing the fake email address, changing the subscription to the newsletter, or changing the extra info (<xref linkend="fig-extra-info">). However, this is planned to be corrected in the future.
</para>
</warning>
</sect2>
<sect2 id="redirect-users-to-login-and-back"><title>How to redirect users to Login and back</title><para>We have already seen how to redirect users to the Login page (<xref linkend="redirect-users-to-login-page">), to the Homepage (<xref linkend="redirect-users-to-homepage">) and to the Forum profile from the Your Info profile (<xref linkend="redirect-your-info-to-forums-user-profile">). Finally, it is time that we consider the general redirection problem:</para><para>You are using some module,<indexterm><primary>module</primary></indexterm> say an eCommerce module like the Emporium Shopping Cart (<xref linkend="PHP-Nuke-eCommerce-module">), and at some point you need to ask the user to login (if not already done) to finish off the order. You would like to redirect the user to the Login screen (<xref linkend="fig-security-code">), then bring him back where he was to continue.</para><para>This is already implemented in <application>PHP-Nuke</application> at some places, like the Private Messages part of the Your Account module:<indexterm><primary>module</primary></indexterm> in the forums for example, if you aren't logged in, you see the link 'Log in to check your private messages', which when clicked on it, takes you to Your Account (address line becomes : http://www.yoursite.com/modules.<indexterm><primary>modules</primary></indexterm>php?name=Your_Account&amp;redirect=privmsg&amp;folder=inbox), and upon login in, you get taken back to PMs.</para><para>To accomplish this from an arbitrary module,<indexterm><primary>module</primary></indexterm> that serves as the starting point for the redirection,<indexterm><primary>redirection</primary></indexterm> open that module's code and find the place where the redirection has to happen. Initiate the redirection with the following two lines:</para><screen><![CDATA[$redirect = $module_name;
]]><![CDATA[<a href=\"modules.php?name=Your_Account&redirect=$redirect\">CLICK HERE TO LOGIN</a>
]]></screen><para>The value of $redirect is what you will key off in the next step. In this example we use the module name as the key that will point the way back, but you can use anything, as long as you know how to use it later, to trace your way back with the right link.</para><para>Now go to modules/Your_Account/index.<indexterm><primary>index</primary></indexterm>php and look for the following code in the login() function:<indexterm><primary>function</primary></indexterm></para><screen><![CDATA[if ($pm_login != "") {
]]><![CDATA[ Header("Location: modules.php?name=Private_Messages&file=index&folder=inbox");
]]><![CDATA[ exit;
]]><![CDATA[ }
]]></screen><para>Add the following after it:</para><screen><![CDATA[if ($redirect == "XXXXXXXXX"){
]]><![CDATA[ Header("Location: modules.php?name=YYYYYYYYY");
]]><![CDATA[ exit;
]]><![CDATA[ }
]]></screen><para>where XXXXXXXXX is the value of $redirect from the first step and YYYYYYYY is the name of the module you want them dumped into after login.<indexterm><primary>login</primary></indexterm></para><para>You might think that we are done by now, but there is a caveat: the above will work as long as they log in correctly on the first try. If they make a mistake and have to try a second or more times, they will get dumped in Your Account,<indexterm><primary>Your Account</primary></indexterm> after they log in successfully, not in the module they came from. This is also true for the Private Messages example above.</para><para>To fix this, find the following code in Your_Account<indexterm><primary>Your_Account</primary></indexterm>\index.<indexterm><primary>index</primary></indexterm>php at the bottom of the login function.</para><screen><![CDATA[} else {
]]><![CDATA[ Header("Location: modules.php?name=$module_name&stop=1");
]]><![CDATA[ }
]]></screen><para>and change it to:</para><screen><![CDATA[} else {
]]><![CDATA[ Header("Location: modules.php?name=$module_name&stop=1&redirect=$redirect");
]]><![CDATA[ }
]]></screen><para>Then it will redirect even if they log in incorrectly the first time. See <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=17779">How to redirect</ulink>.</para></sect2>
<sect2 id="disable-registration"><title>How to disable registration</title><para>If you want to make registration of users impossible, you can apply a variation of the solution in <xref linkend="redirect-your-info-to-forums-user-profile">: you can redirect the users to the main page (index.<indexterm><primary>index</primary></indexterm>php) whenever they try to register (e.g. by clicking on some registration link). Note that just by deleting the registration links from the code (see <xref linkend="find-all-registration-links"> on how to find them), you still can't prevent a determined user from entering</para><screen><![CDATA[http://www.yourdomain.com/modules.php?name=Your_Account&op=new_user
]]></screen><para>in the URL box of his browser by hand, thus triggering the &ldquo;operation new_user<indexterm><primary>new_user</primary></indexterm>&rdquo; in <application>PHP-Nuke</application>. By this, it becomes clear that a real solution must at least change the behaviour of <application>PHP-Nuke</application> for the value &ldquo;new_user<indexterm><primary>new_user</primary></indexterm>&rdquo; of the op URL parameter.<indexterm><primary>parameter</primary></indexterm></para><para>Again, instead of chasing links in the code, there is a more elegant solution:</para><para>In modules/Your_Account/index.<indexterm><primary>index</primary></indexterm>php find the lines:</para><screen><![CDATA[case "new_user":
]]><![CDATA[new_user();
]]><![CDATA[break;
]]></screen><para>and replace them with:</para><screen><![CDATA[case "new_user":
]]><![CDATA[Header("Refresh: 0; url=index.php");
]]><![CDATA[break;
]]></screen><para>This will only disable registration from the Your Account module (more accurately: it will redirect every registration attempt to the main index.<indexterm><primary>index</primary></indexterm>php page).</para><para>To disable it in the Forums too, edit modules/Forums/profile.<indexterm><primary>profile</primary></indexterm>php. Find</para><screen><![CDATA[else if ( $mode == 'editprofile' || $mode == 'register' )
]]><![CDATA[{
]]><![CDATA[ if ( !$userdata['session_logged_in'] && $mode == 'editprofile' )
]]><![CDATA[ {
]]><![CDATA[ $header_location = ( @preg_match("/Microsoft|WebSTAR|Xitami/",
]]><![CDATA[ $_SERVER["SERVER_SOFTWARE"]) ) ? "Refresh: 0; URL=" : "Location: ";
]]><![CDATA[ header($header_location .
]]><![CDATA[ append_sid("login.$phpEx?redirect=profile.$phpEx&mode=editprofile",
]]><![CDATA[ true));
]]><![CDATA[ exit;
]]><![CDATA[ }
]]><![CDATA[ include("includes/usercp_register.php");
]]><![CDATA[ exit;
]]><![CDATA[}
]]></screen><para>and change it to something like:</para><screen><![CDATA[else if ( $mode == 'editprofile' || $mode == 'register' )
]]><![CDATA[{
]]><![CDATA[ Header("Refresh: 0; url=index.php");
]]><![CDATA[ exit;
]]><![CDATA[}
]]></screen><para>i.e. we again redirect the user to the index.<indexterm><primary>index</primary></indexterm>php page. See also <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=18403">How to disable registration</ulink>.</para><tip>
<title>
It's also possible without programming!
</title>
<para>
As so often in life, it all depends on what you want. You can of course achieve a similar effect, without any programming, if you make the Your Account module accessible to admins only, from the modules administration, in the administration panel.
</para>
</tip>
<para>If you want users to be registered directly, without confirmation mails, see <xref linkend="register-users-immediately">. If you want to approve every user who applied for registration,<indexterm><primary>registration</primary></indexterm> you can use the Approve Membership module (see <xref linkend="PHP-Nuke-Approve-Membership-module">).</para></sect2>
<sect2 id="register-users-immediately"><title>How to let users register immediately</title><para>When new users register, you may want them to be able to do so immediately, without having to wait for an email notification with an activation link. </para><caution>
<title>
Do you trust your users?
</title>
<para>
If you let everyone post without being registered, you will not have *any* data as to who wrote that inflammatory, libellous, pornographic or whatever post in your forum that caught FBI's attention. Thus you should really trust your users not to abuse your system, if you plan to bypass email notification on registration.
</para>
</caution>
<para>You have two options, if you are not in the mood of programming it yourself <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject>:</para>
<orderedlist><listitem><para>From the administration panel, Preferences, just choose that non-registered users are allowed to post. Then, from the modules and blocks administration panels, for each module or block you use, choose that all users are allowed to see it. That should come very close to what you want - that all users be able to use all parts of your site without registration. </para></listitem><listitem><para>A module that allows the administrator to bypass email activation is <ulink url="http://www.nukefixes.com/article6.html">NSN Your Account Tweak 650 3.0.2</ulink>. According to the description, administrators can choose to bypass email activation. But the module offers a lot of other useful features around user management, see <xref linkend="NSN-Your-Account-Tweak-module">.</para></listitem></orderedlist><para>See also <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=288">Authorization and avatars</ulink>.</para><caution>
<title>
Download the right NSN Your Account Tweak version!
</title>
<para>
Be careful with the version you download from this module! The number 650, for example, indicates that it is only for <application>PHP-Nuke</application> 6.5. Use only the version that is in accordance with your installed <application>PHP-Nuke</application> version, otherwise you are guaranteed to mess up your installation completely.
</para>
</caution>
<para>See also the <ulink url="http://ravenphpscripts.com/download-file-58.html">New User Auto Activation Hack</ulink> and the <ulink url="http://ravenphpscripts.com/download-file-83.html">Auto Registration Activation For Nuke v7.0</ulink>. If you want to disable registration,<indexterm><primary>registration</primary></indexterm> see <xref linkend="disable-registration">. If you want to approve every user who applied for registration,<indexterm><primary>registration</primary></indexterm> you can use the Approve Membership module (see <xref linkend="PHP-Nuke-Approve-Membership-module">).</para></sect2>
<sect2 id="approve-users"><title>How to approve users before registration</title><para>If you want to enforce the opposite of what is described in <xref linkend="register-users-immediately">, i.e. be able to approve each and every user before he is allowed to register, then you should have a look at the Approve Membership module.<indexterm><primary>module</primary></indexterm> See <xref linkend="PHP-Nuke-Approve-Membership-module"> and <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=83">Authorize accounts</ulink> for more details.</para><para>If you want users to be registered directly, without confirmation mails, see <xref linkend="register-users-immediately">. If you want to disable registration,<indexterm><primary>registration</primary></indexterm> see <xref linkend="disable-registration">.</para></sect2>
<sect2 id="register-users-through-iBill"><title>How to register users through iBill</title><para>Theoretically, you could modify the Your Account module easily to accomodate<indexterm><primary>date</primary></indexterm> for a registration through the <ulink url="http://www.ibill.com">iBill</ulink> credit card option. You could proceed along the following lines (see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=10200">Replacing registration with iBill credit card option</ulink>):</para><para>The iBill system essentially works by users entering information into the iBill script. The script would then connect to the web server and create an account in an .htaccess file (<xref linkend="htaccess-file">) in the <application>PHP-Nuke</application> root directory. When a paid user account would expire,<indexterm><primary>expire</primary></indexterm> iBill's server could then remove the user account from the .htaccess file.</para><para>With iBill controlling the .htaccess file, there would be no need for a Registration option in <application>PHP-Nuke</application>. The only thing that would be needed would be to change the code in block-Login.php, perhaps replacing the Register link with a link to a static html page, where the iBill sign up scripts would do the trick. Or you could just put the iBill code in a block and remove the Register option.</para><para>There is no ready-made solution for this scenario yet, but the procedure<indexterm><primary>procedure</primary></indexterm> outlined above points to the right direction.</para></sect2>
<sect2 id="change-maximum-username-length"><title>How to change the maximum allowed length for user names</title><para>The standard maximum length for user names is 25 characters. If your users really pick up such long nicknames, they may break your blocks' layout,<indexterm><primary>layout</primary></indexterm> depending on your theme and resolution. This is because they may appear as authors of news articles etc. in headlines that appear in various blocks.</para><para>To prevent your users from using long user names, you must change the maximum allowed length in modules/Your_Account/index.php,<indexterm><primary>index.php</primary></indexterm> in the function userCheck(). Find the line:</para><screen><![CDATA[if (strlen($username) > 25) $stop = "<center>"._NICK2LONG."</center>";
]]></screen><para>and change the 25 to a lower length. A better programming style would be to define a constant for this and do the check against the constant.</para></sect2>
</sect1>
<sect1 id="modifying-PHP-Nuke-News-module"><title>Modifying the <application>PHP-Nuke</application> News module</title><para>
<figure id="fig-stories-2">
<title>
Administration panel: Add story.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1148;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1148;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1148;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1148;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Add story.</phrase>
</textobject>
<caption>
<para>Administration panel: Add story.</para>
</caption>
</mediaobject>
</figure>
</para><para>In this section we modify the <application>PHP-Nuke</application> News module,<indexterm><primary>module</primary></indexterm> which is also one of the most important ones:</para><itemizedlist><listitem><para>How to get rid of the need to use &lt;br&gt; for new lines (<xref linkend="get-rid-of-br-in-news">).</para></listitem></itemizedlist><sect2 id="get-rid-of-br-in-news"><title>How to get rid of the need to use &lt;br&gt; for new lines</title><para>It is one of the most annoying requirements for users who want to submit a News article to your site: they have to write the text either in BBcode,<indexterm><primary>BBcode</primary></indexterm> or in HTML.<indexterm><primary>HTML</primary></indexterm> While BBcode is easy to learn and use, HTML can be a real pain for the average Jo user. Worse yet, for sites that have disabled BBcode,<indexterm><primary>BBcode</primary></indexterm> HTML is the only available language for the aspiring journalist. Thus, a lot of people find themselves forced to write their articles with the editor of their choice, then export that document to HTML with the editor's own export function.<indexterm><primary>function</primary></indexterm> Although this scenario will not alleviate the need for a subsequent scrutiny<indexterm><primary>scrutiny</primary></indexterm> of the HTML code thus produced, for the purpose of locating and eliminating the HTML tags that are not allowed by the <application>PHP-Nuke</application> site (see <xref linkend="allow-special-HTML-tags">), it definitely has its merits, especially for long text.</para><para>Those users however, who will rather opt for a quick entering of the text directly in the form fields, will most often be reminded the hard way, by a text totally lacking paragraph structure,<indexterm><primary>structure</primary></indexterm> that something is missing from their text: two break tags (&lt;br&gt;&lt;br&gt;) for the insertion of a blank line, something that is used intuitively to separate paragraphs. Even seasoned HTML coders will find themselves routinely omitting the obligatory &lt;br&gt; tags, so a way to avoid the need for them is great help for both beginners and specialists alike.</para><para>To eliminate the &lt;br&gt; plague once for all, you only have to enter a 2-liner in the modules/news/index.<indexterm><primary>index</primary></indexterm>php file. Find the lines:</para><screen><![CDATA[ getTopics($s_sid);
]]><![CDATA[ formatTimestamp($time);
]]><![CDATA[ $subject = stripslashes($subject);
]]><![CDATA[ $hometext = stripslashes($hometext);
]]><![CDATA[ $notes = stripslashes($notes);
]]><![CDATA[ $introcount = strlen($hometext);
]]><![CDATA[ $fullcount = strlen($bodytext);
]]><![CDATA[ $totalcount = $introcount + $fullcount;
]]><![CDATA[ $c_count = $comments;
]]><![CDATA[ $r_options = "";
]]></screen><para>and append the following two ones to them:</para><screen><![CDATA[ $hometext=nl2br("$hometext");
]]><![CDATA[ $bodytext=nl2br("$bodytext");
]]></screen><para>Then, in the modules/News/article.<indexterm><primary>article</primary></indexterm>php, find the lines </para><screen><![CDATA[if ($notes != "") {
]]><![CDATA[ $notes = "<br><br><b>"._NOTE."</b> <i>$notes</i>";
]]><![CDATA[} else {
]]><![CDATA[ $notes = "";
]]><![CDATA[}
]]><![CDATA[if($bodytext == "") {
]]><![CDATA[ $bodytext = "$hometext$notes";
]]><![CDATA[} else {
]]><![CDATA[ $bodytext = "$hometext<br><br>$bodytext$notes";
]]><![CDATA[}
]]></screen><para>and add in 2 more lines, like this:</para><screen><![CDATA[$hometext = nl2br($hometext);
]]><![CDATA[$bodytext = nl2br($bodytext);
]]></screen><para>The <ulink url="http://www.php.net/manual/en/function.nl2br.php">nl2br <acronym>PHP</acronym> function</ulink> (newline to break) will automatically insert HTML &lt;br /&gt; tags (breaks) before every newline in the short ($hometext) and extended text ($bodytext) of the news article (see also <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=18099">How do I stop using the br tag</ulink>, <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=11513">Linebreaks when entering text</ulink>).</para></sect2>
</sect1>
<sect1 id="modifying-PHP-Nuke-submit-news-module"><title>Modifying the <application>PHP-Nuke</application> Submit News module</title><para>
<figure id="fig-submissions-2">
<title>
Administration panel: Submissions.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1149;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1149;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1149;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1149;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Submissions.</phrase>
</textobject>
<caption>
<para>Administration panel: Submissions.</para>
</caption>
</mediaobject>
</figure>
</para><para>In this section we modify the <application>PHP-Nuke</application> Submit News module:<indexterm><primary>module</primary></indexterm></para><itemizedlist><listitem><para>How to bypass article approval (<xref linkend="bypass-article-approval">).</para></listitem></itemizedlist><sect2 id="bypass-article-approval"><title>How to bypass article approval</title><para>The standard workflow for a news article is that the user writes it, submits it for approval by the administrator,<indexterm><primary>administrator</primary></indexterm> the administrator reads it, approves and publishes it on the site. This has some advantages:</para><itemizedlist><listitem><para>Everybody can post, even anonymous users. </para></listitem><listitem><para>Since the posts are checked, there is no risk of getting flooded with garbage<indexterm><primary>garbage</primary></indexterm> posts.<indexterm><primary>posts</primary></indexterm></para></listitem></itemizedlist><para>But it also has some disadvantages too:</para><itemizedlist><listitem><para>Users have to wait to see their post published. This may not be what they expect, if actuality of content is highly important for the topics of your site.</para></listitem><listitem><para>The administrators have to spend time on approving news articles. Waiting content (<xref linkend="fig-waiting-content-block">) can be quite an administrative headache,<indexterm><primary>headache</primary></indexterm> if the site receives many user submissions a day (see, for example phpnuke.org,<indexterm><primary>phpnuke.org</primary></indexterm> where there are dozens of submissions awaiting approval at any given time).</para></listitem></itemizedlist><para>
<figure id="fig-waiting-content-block">
<title>
Waiting Content block.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1150;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1150;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1150;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1150;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Waiting Content block.</phrase>
</textobject>
<caption>
<para>Waiting Content block.</para>
</caption>
</mediaobject>
</figure>
</para><para>Fortunately, to bypass article approval,<indexterm><primary>approval</primary></indexterm> the solution is relatively simple (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=270">Automatic Article Posting</ulink>):</para><itemizedlist><listitem><para>For versions before <application>PHP-Nuke</application> 6.5:<indexterm><primary>6.5</primary></indexterm></para><para>In the modules/Submit_News, in the function submitStory(), find this </para><screen><![CDATA[$result = sql_query("insert into ".$prefix."_queue
]]><![CDATA[values (NULL, '$uid', '$name', '$subject', '$story',
]]><![CDATA['$storyext', now(), '$topic', '$catid', '$alanguage')", $dbi);
]]></screen><para>Change it to this:</para><screen><![CDATA[$result = sql_query("insert into ".$prefix."_stories
]]><![CDATA[values (NULL, '$catid', '$name', '$subject', now(), '$story',
]]><![CDATA['$storyext', '0', '0', '$topic', '$name', ", '0', '$alanguage',
]]><![CDATA['0','0', '0', '0', '0')", $dbi);
]]></screen><para>The story will get posted immediately, so you will want to make the Submit_News module only available to Users. Also, you will notice that it will now say &ldquo;Posted By Some_user&rdquo;, and it will no longer show in italics. </para></listitem><listitem><para>For <application>PHP-Nuke</application> 6.5 and later, the solution is slightly different. Replace this:</para><screen><![CDATA[$sql = "INSERT INTO ".$prefix."_queue VALUES (NULL, '$uid', '$name', '$subject',
]]><![CDATA['$story', '$storyext', now(), '$topic', '$alanguage')";
]]></screen><para>with this:</para><screen><![CDATA[$sql = "insert into ".$prefix."_stories values (NULL, '$catid', '$name', '$subject',
]]><![CDATA[now(), '$story', '$storyext', '0', '0', '$topic', '$name', ", '0', '$alanguage', '0', '0', '0', '0','0', ")";
]]></screen></listitem></itemizedlist><para>You will also want to change the language file &quot;defines&quot;, or edit these lines in the function submitStory (this is what is displayed when the submission is sent.</para><screen><![CDATA[echo "<center><font class=\"title\">"._SUBSENT."</font><br><br>"
]]><![CDATA[."<font class=\"content\"><b>"._THANKSSUB."</b><br><br>"
]]><![CDATA[.""._SUBTEXT.""
]]><![CDATA[."<br>"._WEHAVESUB." $waiting "._WAITING."";
]]></screen><sect3 id="formatAidHeader-function"><title>The formatAidHeader() function</title><para>If you want to make the &ldquo;Posted By Some_user&rdquo; also be a link to the User's profile,<indexterm><primary>profile</primary></indexterm> then you can edit the function formatAidHeader in your mainfile.php.<indexterm><primary>mainfile.php</primary></indexterm> The following refers to <application>PHP-Nuke</application> 6.5 and above.</para><para>The function is simple: it takes an argument, the author id $aid, searches the nuke_authors table for that author id and, if found, it prints a link to the web page of the author. Only if the web page link fiels of nuke_authors is empty for that author, it prints a link to the author's e-mail (which is always there):</para><screen><![CDATA[function formatAidHeader($aid) {
]]><![CDATA[ global $prefix, $db;
]]><![CDATA[ $sql = "SELECT url, email FROM ".$prefix."_authors WHERE aid='$aid'";
]]><![CDATA[ $result = $db->sql_query($sql);
]]><![CDATA[ $row = $db->sql_fetchrow($result);
]]><![CDATA[ $url = $row[url];
]]><![CDATA[ $email = $row[email];
]]><![CDATA[ if (isset($url)) {
]]><![CDATA[ $aid = "<a href=\"$url\">$aid</a>";
]]><![CDATA[ } elseif (isset($email)) {
]]><![CDATA[ $aid = "<a href=\"mailto:$email\">$aid</a>";
]]><![CDATA[ } else {
]]><![CDATA[ $aid = $aid;
]]><![CDATA[ }
]]><![CDATA[ echo "$aid";
]]><![CDATA[}
]]></screen><para>You could easily change this behaviour. For example, you could take out the check against the $url and leave only the e-mail part, if you wanted the &ldquo;Posted By Some_user&rdquo; to be an e-mail link, rather than a link to a web page (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=351">Change Posted by... Name (Website) to Name (Email)</ulink>):</para><screen><![CDATA[function formatAidHeader($aid) {
]]><![CDATA[ global $prefix, $db;
]]><![CDATA[ $sql = "SELECT url, email FROM ".$prefix."_authors WHERE aid='$aid'";
]]><![CDATA[ $result = $db->sql_query($sql);
]]><![CDATA[ $row = $db->sql_fetchrow($result);
]]><![CDATA[ $url = $row[url];
]]><![CDATA[ $email = $row[email];
]]><![CDATA[ if (isset($email)) {
]]><![CDATA[ $aid = "<a href=\"mailto:$email\">$aid</a>";
]]><![CDATA[ } else {
]]><![CDATA[ $aid = $aid;
]]><![CDATA[ }
]]><![CDATA[ echo "$aid";
]]><![CDATA[}
]]></screen><para>You could make it even more sophisticated,<indexterm><primary>sophisticated</primary></indexterm> by making &ldquo;Posted By Some_user&rdquo; a link to the user's profile (see <xref linkend="redirect-your-info-to-forums-user-profile"> for the related subject of user profile redirection). The formatAidHeader function should then be:</para><screen><![CDATA[function formatAidHeader($aid) {
]]><![CDATA[ global $prefix, $db;
]]><![CDATA[ $sql = "SELECT url, email FROM ".$prefix."_authors WHERE aid='$aid'";
]]><![CDATA[ $result = $db->sql_query($sql);
]]><![CDATA[ if($row = $db->sql_fetchrow($result)) {
]]><![CDATA[ $url = $row[url];
]]><![CDATA[ $email = $row[email];
]]><![CDATA[ if (isset($url)) {
]]><![CDATA[ $aid = "<a href=\"$url\">$aid</a>";
]]><![CDATA[ } elseif (isset($email)) {
]]><![CDATA[ $aid = "<a href=\"mailto:$email\">$aid</a>";
]]><![CDATA[ } else {
]]><![CDATA[ $aid = $aid;
]]><![CDATA[ }
]]><![CDATA[ }else {
]]><![CDATA[ $sql = "SELECT user_id FROM ".$prefix."_users WHERE username='$aid'";
]]><![CDATA[ $result = $db->sql_query($sql);
]]><![CDATA[ $row = $db->sql_fetchrow($result);
]]><![CDATA[ $user_id = $row[user_id];
]]><![CDATA[ $aid = "<a
]]><![CDATA[ href=\"modules.php?name=Forums&file=profile
]]><![CDATA[&mode=viewprofile&u=$user_id\">$aid</a>";
]]><![CDATA[ }
]]><![CDATA[ echo "$aid";
]]><![CDATA[}
]]></screen></sect3>
</sect2>
</sect1>
<sect1 id="modifying-PHP-Nuke-sections-module"><title>Modifying the <application>PHP-Nuke</application> Sections module</title><para>
<figure id="fig-sections-2">
<title>
Administration panel: Sections.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1151;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1151;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1151;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1151;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Sections.</phrase>
</textobject>
<caption>
<para>Administration panel: Sections.</para>
</caption>
</mediaobject>
</figure>
</para><para>In this section we modify the <application>PHP-Nuke</application> Section module:<indexterm><primary>module</primary></indexterm></para><itemizedlist><listitem><para>How to order the articles in the Sections module (<xref linkend="order-articles-in-sections">).</para></listitem></itemizedlist><sect2 id="order-articles-in-sections"><title>How to order the articles in the Sections module</title><para>Sometimes you may not be satisfied with the order of articles in the Sections<indexterm><primary>Sections</primary></indexterm> module.<indexterm><primary>module</primary></indexterm> To change it, edit the following line of the modules/Sections/index.php:<indexterm><primary>index.php</primary></indexterm></para><screen><![CDATA[$result = sql_query("select artid, secid, title, content, counter
]]><![CDATA[from ".$prefix."_seccont where secid=$secid $querylang", $dbi);
]]></screen><para>Change it to<footnote><para>See <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=13447">How to sort in Sections</ulink>.</para></footnote></para><screen><![CDATA[$result = sql_query("select artid, secid, title, content, counter
]]><![CDATA[from ".$prefix."_seccont where secid=$secid $querylang ORDER BY artid DESC", $dbi);
]]></screen><tip>
<title>
Changing the order of results
</title>
<para>
This is a typical example of changing the order of results of a database selection. This was achieved by solely adding "ORDER BY artid DESC" to the SQL query string. In plain text, this means "order the results by descending article id". The "right way" would of course be to sort by time. But lacking an extra timestamp field, we make use of the fact that later articles have a higher id. Thus, sorting by descending id will give last articles first. Think of this simple trick whenever you seek a simple way to change the order of some results.
</para>
</tip>
</sect2>
</sect1>
<sect1 id="modifying-PHP-Nuke-downloads-module"><title>Modifying the <application>PHP-Nuke</application> Downloads module</title><para>
<figure id="fig-downloads-4">
<title>
Administration panel: Downloads.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1152;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1152;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1152;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1152;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Downloads.</phrase>
</textobject>
<caption>
<para>Administration panel: Downloads.</para>
</caption>
</mediaobject>
</figure>
</para><para>In this section we modify the <application>PHP-Nuke</application> Downloads module:<indexterm><primary>module</primary></indexterm></para><itemizedlist><listitem><para>How to add URLs longer than 100 characters in Downloads and Web Links (<xref linkend="URLs-longer-than-100-characters">).</para></listitem></itemizedlist><sect2 id="URLs-longer-than-100-characters"><title>How to add URLs longer than 100 characters in Downloads and Web Links</title><para>Not always is the database the sole culprit when you stumble upon an arbitrary limitation of the functionality: constraints are, for some obscure design<indexterm><primary>sign</primary></indexterm> reason, also eagerly set in the code of <application>PHP-Nuke</application> itself. A typical example of this situation, is the limitation of the URL length in the Downloads and Web_Links modules to just 100 characters. To remove this constraint you need to make changes to the database tables<indexterm><primary>tables</primary></indexterm> <emphasis>and</emphasis> the programming code. </para><para>The database change consists of a MySQL command that changes the length of the relevant field. For the Downloads module,<indexterm><primary>module</primary></indexterm> the relevant field is the &ldquo;url<indexterm><primary>url</primary></indexterm>&rdquo; field in the nuke_downloads_downloads table, for the Web_Links module it is the &ldquo;url<indexterm><primary>url</primary></indexterm>&rdquo; field in the nuke_links_links table. To change its length, type on the MySQL command line</para><screen><![CDATA[alter table nuke_downloads_downloads modify url varchar(200);
]]></screen><para>for the Downloads module,<indexterm><primary>module</primary></indexterm> and</para><screen><![CDATA[alter table nuke_links_links modify url varchar(200);
]]></screen><para>for the Web_links module.<indexterm><primary>module</primary></indexterm> </para><tip>
<title>
Changing the length of database fields
</title>
<para>
If you don't feel comfortable with the MySQL command line, you can use a graphical user interface (GUI) for it, like phpMyAdmin (see <xref linkend="phpmyadmin2">). But you can also pack the above commands in a <acronym>PHP</acronym> program:
</para>
<screen>
<![CDATA[<?php]]>
<![CDATA[include_once("mainfile.php");]]>
<![CDATA[global $prefix, $dbi;]]>
<![CDATA[$result=sql_query("alter table nuke_downloads_downloads modify url varchar(200)", $dbi);]]>
<![CDATA[if (!$result) {]]>
<![CDATA[ print (mysql_error());]]>
<![CDATA[}]]>
<![CDATA[$result=sql_query("alter table nuke_links_links modify url varchar(200)", $dbi);]]>
<![CDATA[if (!$result) {]]>
<![CDATA[ print (mysql_error());]]>
<![CDATA[}]]>
<![CDATA[?>]]>
</screen>
<para>
Upload it to your web server in the <application>PHP-Nuke</application> root directory (the one where config.php and mainfile.php are also located) and point your browser to it. The script even takes care to print a descriptive error message (a good programming practice), if an error occurs.
</para>
</tip>
<para>But you are not done yet: for the length change to really take effect, you must change all <emphasis>relevant</emphasis> occurences of &quot;maxlength&quot;<indexterm><primary>maxlength</primary></indexterm> in the <acronym>PHP</acronym> code to reflect the new length of the field in the various HTML forms. This means searching not only the modules folder, but also the admin folder, for files related to the two modules and containing the string &ldquo;maxlength<indexterm><primary>maxlength</primary></indexterm>&rdquo;. </para><itemizedlist><listitem><para>For the Downloads module,<indexterm><primary>module</primary></indexterm> those are:</para><orderedlist><listitem><para><indexterm><primary>Enumerate</primary></indexterm>The modules/Downloads/index.<indexterm><primary>index</primary></indexterm>php file:</para><screen><![CDATA[.""._FILEURL.": <input type=\"text\" name=\"url\" size=\"50\"
]]><![CDATA[maxlength=\"100\" value=\"http://\"><br>";
]]><![CDATA[.""._URL.":<br><input type=\"text\" name=\"url\" value=\"$url\" size=\"50\"
]]><![CDATA[maxlength=\"100\"><br><br>"
]]></screen></listitem><listitem><para>The admin/modules/download.php file:</para><screen><![CDATA[.""._FILEURL.": <input type=\"text\" name=\"url\" value=\"$url\" size=\"50\"
]]><![CDATA[maxlength=\"100\">&nbsp;[ <a target=\"_blank\" href=\"$url\">"._CHECK."</a> ]<br>"
]]><![CDATA[.""._FILEURL.": <input type=\"text\" name=\"url\" size=\"50\"
]]><![CDATA[maxlength=\"100\" value=\"http://\"><br>";
]]><![CDATA[.""._PAGEURL.": <input type=\"text\" name=\"url\" value=\"$url\" size=\"50\"
]]><![CDATA[maxlength=\"100\">&nbsp;[ <a href=\"$url\">"._CHECK."</a> ]<br>"
]]></screen></listitem></orderedlist></listitem><listitem><para>For the Web Links module,<indexterm><primary>module</primary></indexterm> they are:</para><orderedlist><listitem><para>The modules/Web_Links/index.<indexterm><primary>index</primary></indexterm>php file:</para><screen><![CDATA[.""._PAGEURL.": <input type=\"text\" name=\"url\" size=\"50\"
]]><![CDATA[maxlength=\"100\" value=\"http://\"><br>";
]]><![CDATA[.""._URL.":<br><input type=\"text\" name=\"url\" value=\"$url\" size=\"50\"
]]><![CDATA[maxlength=\"100\"><br><br>"
]]></screen></listitem><listitem><para>The admin/modules/links.php file:</para><screen><![CDATA[.""._PAGEURL.": <input type=\"text\" name=\"url\" value=\"$url\" size=\"50\"
]]><![CDATA[maxlength=\"100\">&nbsp;[ <a target=\"_blank\" href=\"$url\">"._VISIT."</a> ]<br>"
]]><![CDATA[.""._PAGEURL.": <input type=\"text\" name=\"url\" size=\"50\"
]]><![CDATA[maxlength=\"100\" value=\"http://\"><br>";
]]><![CDATA[.""._PAGEURL.": <input type=\"text\" name=\"url\" value=\"$url\" size=\"50\"
]]><![CDATA[maxlength=\"100\">&nbsp;[ <a href=\"$url\">Visit</a> ]<br>"
]]><![CDATA[.""._PAGEURL.": <input type=\"text\" name=\"url\" value=\"$url\" size=\"50\"
]]><![CDATA[maxlength=\"100\">&nbsp;[ <a target=\"_blank\" href=\"$url\">"._VISIT."</a> ]<br>"
]]></screen></listitem></orderedlist></listitem></itemizedlist><tip>
<title>
Search for "maxlength" thoroughly!
</title>
<para>
If it still does not work, then you forgot to change "maxlength" somewhere - perhaps in a file under the admin folder. Search thoroughly!
</para>
</tip>
</sect2>
</sect1>
<sect1 id="modifying-PHP-Nuke-stories-archive"><title>Modifying the <application>PHP-Nuke</application> Stories Archive module</title><para>
<figure id="fig-stories-3">
<title>
Administration panel: Add story.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1153;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1153;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1153;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1153;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Add story.</phrase>
</textobject>
<caption>
<para>Administration panel: Add story.</para>
</caption>
</mediaobject>
</figure>
</para><para>In this section we modify the <application>PHP-Nuke</application> Stories Archive module:<indexterm><primary>module</primary></indexterm></para><itemizedlist><listitem><para>How to order the articles in the Stories Archive module (<xref linkend="order-articles-in-stories-archive">).</para></listitem></itemizedlist><sect2 id="order-articles-in-stories-archive"><title>How to order the articles in the Stories Archive module</title><para>Sometimes you may wish a different order of articles in the Stories module.<indexterm><primary>module</primary></indexterm> To change the article order so that the articles appear in alphabetical topic order, instead of a LIFO (last-in-first-out) order, edit the following line of the modules/Sections/index.php:<indexterm><primary>index.php</primary></indexterm></para><screen><![CDATA[$result = sql_query("select sid, catid, title, time, comments, counter, topic,
]]><![CDATA[alanguage, score, ratings from ".$prefix."_stories order by sid DESC
]]><![CDATA[limit $min,$max", $dbi);
]]></screen><para>Change it to (see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=13604">Sorting the Stories Archive by Topic first</ulink>):</para><screen><![CDATA[$result = sql_query("select sid, catid, title, time, comments, counter, topic,
]]><![CDATA[alanguage, score, ratings from ".$prefix."_stories order by topic ASC
]]><![CDATA[limit $min,$max", $dbi);
]]></screen><tip>
<title>
Changing the order of results
</title>
<para>
This is a typical example of changing the order of results of a database selection. This was achieved by solely replacing "ORDER BY sid DESC" with "ORDER BY topic ASC" in the SQL query string. In plain text, this means "order the results by ascending topic". Whenever you are not satisfied with the order of your results, you will know that you have to add or change an ORDER BY clause to an SQL query string somewhere in your module. Of course, you will still have to find where, but hopefully there will be only a few calls to sql_query() in the code, so that, in the worst case, you could try them all and find the one that works.
</para>
</tip>
</sect2>
</sect1>
</chapter>
<chapter id="modifying-PHP-Nuke-admin-panel"><title>Modifying the <application>PHP-Nuke</application> administration panel</title><para>
<figure id="fig-admin-panel-2">
<title>
Administration panel.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1154;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1154;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1154;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1154;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel.</phrase>
</textobject>
<caption>
<para>Administration panel.</para>
</caption>
</mediaobject>
</figure>
</para><para>This chapter is devoted to modifications of the administration panel - a rather exotic topic, but with interesting applications:<indexterm><primary>ations</primary></indexterm></para><itemizedlist><listitem><para>How to set an arbitrary &quot;Stories Number in Home&quot; (<xref linkend="set-arbitrary-stories-number-in-home">),</para></listitem><listitem><para>How to allow HTML in the Newsletter (<xref linkend="allow-HTML-newsletter">).</para></listitem></itemizedlist><sect1 id="set-arbitrary-stories-number-in-home"><title>How to set an arbitrary &quot;Stories Number in Home&quot;</title><para>
<figure id="fig-preferences-3">
<title>
Administration panel: Preferences.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1155;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1155;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1155;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1155;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Preferences.</phrase>
</textobject>
<caption>
<para>Administration panel: Preferences.</para>
</caption>
</mediaobject>
</figure>
</para><para>You want to display only, say, 3 News on the hopepage of your <application>PHP-Nuke</application>. But in the administration panel you get only the options to change the &quot;Stories Number in Home&quot; to 5, 10, 15, 20 , 25 and 30.</para><para>Go to admin/modules/settings.<indexterm><primary>settings</primary></indexterm>php and change at line 61<footnote><para>Line numbers are subject to change. If you don't find what you expected, search for it. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject></para>
</footnote>:</para><screen><![CDATA[ ."</td></tr><tr><td>"
]]><![CDATA[ .""._STORIESHOME.":</td><td><select name='xstoryhome'>"
]]><![CDATA[ ."<option name='xstoryhome'>$storyhome</option>"
]]><![CDATA[ ."<option name='xstoryhome'>5</option>"
]]><![CDATA[ ."<option name='xstoryhome'>10</option>"
]]><![CDATA[ ."<option name='xstoryhome'>15</option>"
]]><![CDATA[ ."<option name='xstoryhome'>20</option>"
]]><![CDATA[ ."<option name='xstoryhome'>25</option>"
]]><![CDATA[ ."<option name='xstoryhome'>30</option>"
]]><![CDATA[ ."</select>"
]]></screen><para>to </para><screen><![CDATA[ ."</td></tr><tr><td>"
]]><![CDATA[ .""._STORIESHOME.":</td><td><select name='xstoryhome'>"
]]><![CDATA[ ."<option name='xstoryhome'>$storyhome</option>"
]]><![CDATA[ ."<option name='xstoryhome'>3</option>"
]]><![CDATA[ ."<option name='xstoryhome'>5</option>"
]]><![CDATA[ ."<option name='xstoryhome'>10</option>"
]]><![CDATA[ ."<option name='xstoryhome'>15</option>"
]]><![CDATA[ ."<option name='xstoryhome'>20</option>"
]]><![CDATA[ ."<option name='xstoryhome'>25</option>"
]]><![CDATA[ ."<option name='xstoryhome'>30</option>"
]]><![CDATA[ ."</select>"
]]></screen><para>Now you can select &quot;3&quot; from the drop-down list. You get the idea. See <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=40">How to set an arbitrary "Stories Number in Home"</ulink>.</para></sect1>
<sect1 id="allow-HTML-newsletter"><title>How to allow HTML in the Newsletter</title><para>
<figure id="fig-newsletter-2">
<title>
Administration panel: Newsletter.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1156;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1156;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1156;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1156;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Newsletter.</phrase>
</textobject>
<caption>
<para>Administration panel: Newsletter.</para>
</caption>
</mediaobject>
</figure>
</para><para>If you want to use HTML,<indexterm><primary>HTML</primary></indexterm> instead of only plain text in the Newsletter from the administration panel,<indexterm><primary>panel</primary></indexterm> you have to do the following:</para><para>Replace the function newsletter_send() in admin/modules/newsletter.<indexterm><primary>newsletter</primary></indexterm>php with:</para><screen><![CDATA[function newsletter_send($title, $content) {
]]><![CDATA[ global $user_prefix, $sitename, $dbi, $nukeurl, $adminmail;
]]><![CDATA[ $send_html_messages = "yes";
]]><![CDATA[ $from = $adminmail;
]]><![CDATA[ $subject = "[$sitename Newsletter]: ".stripslashes($title)."";
]]><![CDATA[ $content = stripslashes($content);
]]><![CDATA[ $content = "$sitename "._NEWSLETTER."\n\n\n$content\n\n-
]]><![CDATA[$sitename "._STAFF."\n\n\n\n\n\n"._NLUNSUBSCRIBE."";
]]><![CDATA[ $result = sql_query("select email from ".$user_prefix.
]]><![CDATA["_users where newsletter='1'", $dbi);
]]><![CDATA[ while(list($email) = sql_fetch_row($result, $dbi)) {
]]><![CDATA[ $xheaders = "From: " . $sitename . " <" . $adminmail . ">\n";
]]><![CDATA[ $xheaders .= "X-Sender: <" . $adminmail . ">\n";
]]><![CDATA[ $xheaders .= "X-Mailer: PHP\n"; // mailer
]]><![CDATA[ $xheaders .= "X-Priority: 6\n"; // Urgent message!
]]><![CDATA[ if ($send_html_messages == "yes") {
]]><![CDATA[ $xheaders .= "Content-Type: text/html;
]]><![CDATA[charset=iso-8859-1\n"; // Mime type
]]><![CDATA[ }
]]><![CDATA[ mail("$email","$subject","$content",$xheaders);
]]><![CDATA[ }
]]><![CDATA[ Header("Location: admin.php?op=newsletter_sent");
]]><![CDATA[}
]]></screen><para>and the function massmail_send() with </para><screen><![CDATA[function massmail_send($title, $content) {
]]><![CDATA[ global $user_prefix, $sitename, $dbi, $nukeurl, $adminmail;
]]><![CDATA[ $send_html_messages = "yes";
]]><![CDATA[ $from = $adminmail;
]]><![CDATA[ $subject = "[$sitename]: $title";
]]><![CDATA[ $content = stripslashes($content);
]]><![CDATA[ $content = ""._FROM.": $sitename\n\n\n\n$content\n\n\n\n-
]]><![CDATA[ $sitename "._STAFF."\n\n\n\n"._MASSEMAILMSG."";
]]><![CDATA[ $result = sql_query("select email from ".$user_prefix
]]><![CDATA[ ."_users where uid != '1'", $dbi);
]]><![CDATA[ while(list($email) = sql_fetch_row($result, $dbi)) {
]]><![CDATA[ $xheaders = "From: " . $sitename . " <" . $adminmail . ">\n";
]]><![CDATA[ $xheaders .= "X-Sender: <" . $adminmail . ">\n";
]]><![CDATA[ $xheaders .= "X-Mailer: PHP\n"; // mailer
]]><![CDATA[ $xheaders .= "X-Priority: 6\n"; // Urgent message!
]]><![CDATA[ if ($send_html_messages == "yes") {
]]><![CDATA[ $xheaders .= "Content-Type: text/html;
]]><![CDATA[ charset=iso-8859-1\n"; // Mime type
]]><![CDATA[ }
]]><![CDATA[ mail("$email","$subject","$content",$xheaders);
]]><![CDATA[ }
]]><![CDATA[ Header("Location: admin.php?op=massmail_sent");
]]><![CDATA[}
]]></screen><para>The changes are in both functions the same: a flag, $send_html_messages, is checked and if set to &quot;yes&quot;, the headers of the Newsletter mails (stored in the $xheaders variable) get an extra line for the MIME type:</para><screen><![CDATA[Content-Type: text/html; charset=iso-8859-1
]]></screen><para>See also <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=13945">HTML Newsletter</ulink>, but be warned that the code presented in that link, may not escape double quotes,<indexterm><primary>quotes</primary></indexterm> probabbly due to an upgrade bug in the forums.</para></sect1>
</chapter>
<chapter id="blocks"><title>Creating <application>PHP-Nuke</application> blocks</title><para>
<figure id="fig-blocks-2">
<title>
Administration panel: Blocks.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1157;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1157;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1157;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1157;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Blocks.</phrase>
</textobject>
<caption>
<para>Administration panel: Blocks.</para>
</caption>
</mediaobject>
</figure>
</para><para>Having seen how to <emphasis>modify</emphasis> a <application>PHP-Nuke</application> block (<xref linkend="modifying-php-nuke-blocks">), we can gradually try our skills in <emphasis>creating</emphasis> one. We proceed by showing:</para><itemizedlist><listitem><para>The characteristics of the various types of blocks (<xref linkend="block-types">),</para></listitem><listitem><para>How to create a new block (<xref linkend="block-creation">),</para></listitem><listitem><para>A simple Content block (<xref linkend="Simple-Content-block">),</para></listitem><listitem><para>How to include PHP/HTML files in a <application>PHP-Nuke</application> block (<xref linkend="how-to-include-files">),</para></listitem><listitem><para>How to use Javascript in <application>PHP-Nuke</application> blocks (<xref linkend="javascript-in-php-nuke-blocks">),</para></listitem><listitem><para>How to display Flash in <application>PHP-Nuke</application> blocks (<xref linkend="flash-php-nuke-blocks">),</para></listitem><listitem><para>How to show advertisements in <application>PHP-Nuke</application> blocks (<xref linkend="advertisements-in-php-nuke-blocks">),</para></listitem><listitem><para>How to display images in <application>PHP-Nuke</application> blocks (<xref linkend="display-images-php-nuke-blocks">),</para></listitem><listitem><para>How to display HTML forms in a block:<indexterm><primary>block</primary></indexterm> Paypal (<xref linkend="paypal-block-for-php-nuke">).</para></listitem></itemizedlist><sect1 id="block-types"><title>The characteristics of the various types of blocks</title><para>There are 3 different types of <application>PHP-Nuke</application> blocks:</para><itemizedlist><listitem><para>RSS/RDF:<indexterm><primary>RDF</primary></indexterm> They capture news that's available from other sites in standard reading format, i.e. text (For example the site <ulink url="www.spaghettibrain.com">spaghettibrain</ulink> has a lot of news that are at other sites' disposal).</para></listitem><listitem><para>Blocks of contents:<indexterm><primary>contents</primary></indexterm> blocks in which we insert simple text or HTML text that will be then displayed inside the block (See following example)</para></listitem><listitem><para>Blocks of files: They are <acronym>PHP</acronym> scripts that execute fixed commands (see <xref linkend="block-creation">)</para></listitem></itemizedlist><para>In this paragraph we will see a simple example of how to insert the links and the text in a text block.<indexterm><primary>block</primary></indexterm> If you already know a little HTML there is no point in following this example.</para><para>We suppose you want to insert a block with text and a link to 3 different sites:</para><para>The Webmaster who wrote this book manages the following sites:</para><itemizedlist><listitem><para><ulink url="http://www.spaghettibrain.com">spaghettibrain.com</ulink></para></listitem><listitem><para><ulink url="http://www.spaghettiopen.com">spaghettiopen.com</ulink></para></listitem><listitem><para><ulink url="http://www.spaghettipython.com">spaghettipython.com</ulink></para></listitem></itemizedlist><para>The text will be formatted in this way in order to be inserted in the block<indexterm><primary>block</primary></indexterm> (see <xref linkend="fig-block-example">):</para><screen><![CDATA[<B> webmaster </b> who writes this book manages the following sites: <b ><br>
]]><![CDATA[<a href="http://www.spaghettibrain.com">spaghettibrain.com</a>
]]><![CDATA[<a href ="http://www.claudioerba.com">claudioerba.com</a>
]]></screen><para>
<figure id="fig-block-example">
<title>
Block example
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1158;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1158;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1158;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1158;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Block example</phrase>
</textobject>
<caption>
<para>Block example</para>
</caption>
</mediaobject>
</figure>
</para><para>Some Small HTML lessons:</para><variablelist><varlistentry><term>&lt;b&gt;
</term><listitem><para>It is for bold text, it opens a tag. All words that we write after this tag will be bold until &lt;/B&gt; (which closes the tag).</para></listitem></varlistentry><varlistentry><term>&lt;br&gt;
</term><listitem><para>It is for a page break, it does not need to be closed.</para></listitem></varlistentry><varlistentry><term>&lt;ahref=&quot;http://siteyouwant.com&quot;&gt;SiteName&lt;/a&gt;
</term><listitem><para>is used to open the http://siteyouwant.com.</para></listitem></varlistentry></variablelist></sect1>
<sect1 id="block-creation"><title>How to create a new block</title><para>To create a block of the third type, i.e. a php script that interfaces with the database and extrapolates the data,<indexterm><primary>data</primary></indexterm> first of all we have to understand how these blocks are structured. They are contained in a folder called blocks, the name of the block must be block-blockname.php. It is very important all blocks start with &ldquo;block-&rdquo; . Every block in which the name will start with block- will be included in the screen of the blocks that can be activated.<indexterm><primary>activated</primary></indexterm> We will find in the blocks administration menu all the available blocks in the file_name drop-down list. If not assigned by the administrator,<indexterm><primary>administrator</primary></indexterm> the name will be the same that follows block- We can't use break spaces in a block name, they must be replaced by using underscore _ . All the blocks that will respect these rules will be inserted in the blocks admin menu.<indexterm><primary>menu</primary></indexterm></para><para>We describe:</para><itemizedlist><listitem><para>How to create a block,<indexterm><primary>block</primary></indexterm> theoretical approach (<xref linkend="block-theory">),</para></listitem><listitem><para>How to create a block,<indexterm><primary>block</primary></indexterm> a practical example (<xref linkend="block-practice">).</para></listitem></itemizedlist><sect2 id="block-theory"><title>How to create a block, theoretical approach</title><para>You have to follow these rules when creating a block:<indexterm><primary>block</primary></indexterm></para><itemizedlist><listitem><para>In every block you create you have to insert the following code at the beginning:</para><screen><![CDATA[if (eregi("block-Name_of_Block.php", $PHP_SELF)) {
]]><![CDATA[Header("Location: index.php");
]]><![CDATA[die();
]]><![CDATA[}
]]></screen><para>By using this code you protect the file avoiding users approaching it directly from the blocks folder, and the block will be displayed only when selected from your site. </para></listitem><listitem><para>In the blocks you can include everything you want, Perl, java, php, flash<indexterm><primary>flash</primary></indexterm> etc...</para></listitem><listitem><para>All the block output must have a value that can be obtained from the variable $content.</para></listitem></itemizedlist><para>Remember that you have a limited amount of space in the block,<indexterm><primary>block</primary></indexterm> pay special attention to the layout!</para><warning>
<title>
Warning
</title>
<para>
In order to have W3C standard compatible blocks, Francisco Burzi says:
<blockquote><para>&quot;To respect the W3c standards for HTML 4.01 Transitional,<indexterm><primary>Transitional</primary></indexterm> it is very important that you replace all &quot;instances of &amp;&quot; in the URL by the tag &quot;&amp;amp; &quot; </para></blockquote>For example the URL:
<screen><![CDATA[<a href="modules.php?op=modload&name=FAQ&file=index">
]]></screen>must be written:
<screen><![CDATA[<a href="modules.php?op=modload&amp;name=FAQ&amp;file=index">
]]></screen>and don't use, for example, the tag "li" (used to create a list), but leave that in the style sheet (CSS) which will make it for you.
</para>
</warning>
<para>The background for the tables and font etc., are better left to the style sheet (CSS).</para><para>We will now see how to construct a block starting from the beginning.</para></sect2>
<sect2 id="block-practice"><title>How to create a block, a practical example</title><para>We will make a very simple block that shows the pages visited in our site the day before. We'll have a single query and a single value, in order to make things easier. Our block is called &quot;hits&quot;, so the complete name of the block will be block-hits.php</para><para>First of all, we open the php tag</para><screen><![CDATA[<?php
]]></screen><para>Then we insert the protection script we've seen before:</para><screen><![CDATA[if (eregi("block-hits.php", $PHP_SELF)) {
]]><![CDATA[Header("Location: index.php");
]]><![CDATA[die();
]]><![CDATA[}
]]></screen><para>And now we insert the variables that we want to call (in this case the parameter<indexterm><primary>parameter</primary></indexterm> $prefix and $dbi, which handles the database abstraction): </para><screen><![CDATA[global $prefix, $dbi;
]]></screen><para>Now we continue inserting the query that reads from the database how many pages were seen in our site: (the instruction would be &ldquo;read the first line value of the table nuke_counter in the cell count&rdquo;) </para><screen><![CDATA[$result = sql_query("select count from "$prefix."_counter
]]><![CDATA[ order by type desc limit 0.1", $dbi);
]]><![CDATA[list($count) = sql_fetch_row($result, $dbi);
]]></screen><para>Finally, we pass the &ldquo;$content&rdquo; variable that will be echoed by the block and close the <acronym>PHP</acronym> tag: </para><screen><![CDATA[$content. = $count
]]><![CDATA[?>
]]></screen><para>Our complete script will be :</para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[if (eregi("block-hits,php", $PHP_SELF)) {
]]><![CDATA[ Header("Location: index.php");
]]><![CDATA[ die();
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[global $prefix, $dbi;
]]><![CDATA[
]]><![CDATA[$result = sql_query("select count from "$prefix."_counter
]]><![CDATA[ order by type desc limit 0.1", $dbi);
]]><![CDATA[list($count) = sql_fetch_row($result, $dbi);
]]><![CDATA[
]]><![CDATA[$content. = $count
]]><![CDATA[
]]><![CDATA[?>
]]></screen></sect2>
</sect1>
<sect1 id="Simple-Content-block"><title>Simple Content block</title><para>
<figure id="fig-content-2">
<title>
Administration panel: Content.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1159;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1159;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1159;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1159;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Content.</phrase>
</textobject>
<caption>
<para>Administration panel: Content.</para>
</caption>
</mediaobject>
</figure>
</para><para>PHP-Nuke comes with a Content module (<xref linkend="fig-content-2">). But how about a Content block<indexterm><primary>block</primary></indexterm>? How to display links to Content pages in a <application>PHP-Nuke</application> block?<indexterm><primary>block</primary></indexterm> A block may be desirable in case you wish to place a link summary of the Content module's er...content, somewhere in the left, central or right columns.</para><para>After you have created the desired categories for the Content module,<indexterm><primary>module</primary></indexterm> you can then go to http://yoursite.com/admin.php?<indexterm><primary>admin.php</primary></indexterm>op=content and start adding pages to the categories. To find out the link to these pages, you will have to click on the Content<indexterm><primary>Content</primary></indexterm> link in the modules block,<indexterm><primary>block</primary></indexterm> view each page and copy its url from the browser's address window, then just add these urls to a html block with maybe the following HTML code:</para><screen><![CDATA[&nbsp;&nbsp;<b><big>&middot;</big></b> <img src=images/blocks/icon_dot.gif>
]]><![CDATA[&nbsp;<a href="modules.php?name=Content...etc...1">Page Title 1</a><BR>
]]><![CDATA[&nbsp;&nbsp;<b><big>&middot;</big></b> <img src=images/blocks/icon_dot.gif>
]]><![CDATA[&nbsp;<a href="modules.php?name=Content...etc...2">Page Title 2</a><BR>
]]><![CDATA[&nbsp;&nbsp;<b><big>&middot;</big></b> <img src=images/blocks/icon_dot.gif>
]]><![CDATA[&nbsp;<a href="modules.php?name=Content...etc...3">Page Title 3</a><BR>
]]><![CDATA[&nbsp;&nbsp;<b><big>&middot;</big></b> <img src=images/blocks/icon_dot.gif>
]]><![CDATA[&nbsp;<a href="modules.php?name=Content...etc...4">Page Title 4</a><BR>
]]><![CDATA[&nbsp;&nbsp;<b><big>&middot;</big></b> <img src=images/blocks/icon_dot.gif>
]]><![CDATA[&nbsp;<a href="modules.php?name=Content...etc...5">Page Title 5</a><BR>
]]></screen><para>A block that does the job is the following:</para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[if (eregi("block-Content.php",$PHP_SELF)) {
]]><![CDATA[ Header("Location: index.php");
]]><![CDATA[ die();
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[$content = "&nbsp;&nbsp;<b><big>&middot;</big></b> <img src=images/blocks/icon_dot.gif>
]]><![CDATA[&nbsp;<a href=\"modules.php?name=Content...etc...1\">Page Title 1</a><BR>";
]]><![CDATA[$content .= "nbsp;&nbsp;<b><big>&middot;</big></b> <img src=images/blocks/icon_dot.gif>
]]><![CDATA[&nbsp;<a href=\"modules.php?name=Content...etc...2\">Page Title 2</a><BR>";
]]><![CDATA[$content .= "nbsp;&nbsp;<b><big>&middot;</big></b> <img src=images/blocks/icon_dot.gif>
]]><![CDATA[&nbsp;<a href=\"modules.php?name=Content...etc...3\">Page Title 3</a><BR>";
]]><![CDATA[$content .= "nbsp;&nbsp;<b><big>&middot;</big></b> <img src=images/blocks/icon_dot.gif>
]]><![CDATA[&nbsp;<a href=\"modules.php?name=Content...etc...4\">Page Title 4</a><BR>";
]]><![CDATA[$content .= "nbsp;&nbsp;<b><big>&middot;</big></b> <img src=images/blocks/icon_dot.gif>
]]><![CDATA[&nbsp;<a href=\"modules.php?name=Content...etc...5\">Page Title 5</a><BR>";
]]><![CDATA[
]]><![CDATA[?>
]]></screen><para>Name it block-Content,<indexterm><primary>Content</primary></indexterm> put it in the blocks folder, then &quot;create&quot; it in the blocks administration (see <xref linkend="administration-functions">). </para></sect1>
<sect1 id="how-to-include-files"><title>How to include PHP/HTML files in a <application>PHP-Nuke</application> block</title><para>Suppose you want to write a block,<indexterm><primary>block</primary></indexterm> block-bar.php, that includes the file foo/bar.php. The way <application>PHP-Nuke</application> displays a block is that it first includes the block,<indexterm><primary>block</primary></indexterm> with a statement like </para><screen><![CDATA[include("blocks/block-bar.php");
]]></screen><para>then makes a table and puts in the title,<indexterm><primary>title</primary></indexterm> and makes another table row, and &quot;echo&quot;es the $content variable. Thus, the $content variable must contain all the output of foo/bar.php, if your block has to contain its output. The <acronym>PHP</acronym> output control functions come in here very handy. The <ulink url="http://www.php.net/manual/en/ref.outcontrol.php">PHP output control functions</ulink> allow you to control when output is sent from the script. This can be useful in various situations,<indexterm><primary>ations</primary></indexterm> especially if you need to send headers to the browser after your script has began outputting data.<indexterm><primary>data</primary></indexterm> The output control functions (or output buffering functions, as they are often called and as the ob_ prefix in their name suggests) do not affect headers sent using header() or setcookie(), only functions such as echo() and data between blocks of <acronym>PHP</acronym> code.</para><para>Output buffering is a powerful tool in <acronym>PHP</acronym> which allows you to buffer a script's output. You can even edit this buffer before returning it to the client. The <acronym>PHP</acronym> functions that constitute the output buffering toolbox are:</para><itemizedlist><listitem><para>ob_start([callback function]) - Starts an output buffering session.<indexterm><primary>session</primary></indexterm></para></listitem><listitem><para>ob_flush() - Send the contents of the buffer to the client and clear the buffer.<indexterm><primary>buffer</primary></indexterm></para></listitem><listitem><para>ob_get_contents() - Returns the contents of the buffer.<indexterm><primary>buffer</primary></indexterm> The buffer is not cleared. </para></listitem><listitem><para>ob_end_clean() - Ends the current buffering session and purges the buffer.<indexterm><primary>buffer</primary></indexterm> </para></listitem><listitem><para>ob_end_flush() - Ends the current buffering session and displays the buffer.<indexterm><primary>buffer</primary></indexterm></para></listitem><listitem><para>ob_get_length() - (Version &gt;= 4.0.2) Return the size of the current buffer.<indexterm><primary>buffer</primary></indexterm> </para></listitem><listitem><para>ob_get_clean() - (Version &gt;= 4.3) Composite of ob_get_contents() and</para></listitem><listitem><para>ob_end_clean(). The buffer is returned and the session ends.</para></listitem></itemizedlist><para>How can we use output buffering to include the output of foo/bar.php in our <application>PHP-Nuke</application> block?<indexterm><primary>block</primary></indexterm> The idea is simple: rather than having <acronym>PHP</acronym> send output directly to the standard output device (the browser) as the script gets executed, we will define a special output buffer which stores all the output generated by the script during its lifetime. When we do this, the output of the script is never seen by the user unless we explicitly make the contents of this buffer visible via a call to PHP's output control API (through one of the above functions). We put the foo folder in the main phpnuke directory, and use this code our block:<indexterm><primary>block</primary></indexterm></para><screen><![CDATA[ob_start();
]]><![CDATA[include("foo/bar.php");
]]><![CDATA[$output = ob_get_contents();
]]><![CDATA[ob_end_clean();
]]><![CDATA[$content = $output;
]]></screen><para>This way the $content variable will contain the output of foo/bar.php, which will thus be shown in the block.<indexterm><primary>block</primary></indexterm> To learn more about <acronym>PHP</acronym> output buffering,<indexterm><primary>buffering</primary></indexterm> see <ulink url="http://www.devshed.com/Server_Side/PHP/OutputBuffering/">Output Buffering with PHP</ulink> and <ulink url="http://jinxidoru.com/tutorials/buffering.html">PHP Output Buffering tutorial</ulink>. See also <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=11465">Scripting a new Block Problem</ulink>, for a complete example of including a <acronym>PHP</acronym> scoring application in a <application>PHP-Nuke</application> block.<indexterm><primary>block</primary></indexterm></para></sect1>
<sect1 id="javascript-in-php-nuke-blocks"><title>How to use Javascript in <application>PHP-Nuke</application> blocks</title><para>Javascript can be used with <application>PHP-Nuke</application> without problems, as long as you remember that they operate in different environments (see <ulink url="http://forums.devnetwork.net/viewtopic.php?t=1030">Frames, JavaScript, and <acronym>PHP</acronym> Overview</ulink>):</para><itemizedlist><listitem><para>PHP-Nuke, like PHP,<indexterm><primary>PHP</primary></indexterm> is server side. Therefore, if you want to pass data from a form to PHP-Nuke, you <emphasis>have to</emphasis> submit it and load the page again. There is no getting around it.</para></listitem><listitem><para>Javascript is client side (run in the browser), and can help you with dynamic<indexterm><primary>dynamic</primary></indexterm> functionality.<indexterm><primary>functionality</primary></indexterm> You can easily use JavaScript and <application>PHP-Nuke</application> together. However, just like PHP,<indexterm><primary>PHP</primary></indexterm> <application>PHP-Nuke</application> knows <emphasis>nothing</emphasis> about Javascript.<indexterm><primary>Javascript</primary></indexterm> <application>PHP-Nuke</application> will just echo the Javascript code to the HTML page, just as it would echo the value of a string variable.</para></listitem></itemizedlist><para>Thus, from the point of view of <acronym>PHP</acronym> and PHP-Nuke, there is no difference between </para><screen><![CDATA[<?php
]]><![CDATA[echo 'Welcome to PHP-Nuke';
]]><![CDATA[?>
]]></screen><para>and</para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[echo '<script type="text/javascript">
]]><![CDATA[<!--
]]><![CDATA[if ( 1 ) {
]]><![CDATA[ window.open(\'modules.php?name=News\', \'_WELCOME\',
]]><![CDATA[ \'HEIGHT=450, resizable=yes, WIDTH=600\');
]]><![CDATA[}
]]><![CDATA[//-->
]]><![CDATA[</script>';
]]><![CDATA[
]]><![CDATA[?>
]]></screen><para>They both echo strings,<indexterm><primary>strings</primary></indexterm> of which the first one is simply displayed in the client's browser as a welcome message, while the second one is interpreted by the client's browser and leads to the browser sending a request for the News module,<indexterm><primary>module</primary></indexterm> which in turn sends the usual home page of a <application>PHP-Nuke</application> site to be displayed on the client.</para><para>With this in mind, Javascript does not demand any special treatment when used in <application>PHP-Nuke</application> blocks. Just append the Javascript code to the $content variable of the block and you are done. Of course, you have to escape double quotes - and it is a good idea to add a newline (\n) to the end of each Javascript line (see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=13048">Javascript and BLOCKs</ulink>). </para><para>If you use <ulink url="http://www.gnu.org/software/sed/manual/sed.html">sed</ulink>, the following sequence of sed commands, applied to a Javascript file, will produce the right <acronym>PHP</acronym> code to include in the <application>PHP-Nuke</application> block:<indexterm><primary>block</primary></indexterm></para><screen>
1,$s/"/\\"/g <co id="sed1">
1,$s/^/\$content \.= "/ <co id="sed2">
1,$s/$/";/ <co id="sed3">
1,$s/";$/\\n";/ <co id="sed4">
</screen>
<calloutlist>
<callout arearefs="sed1">
<para>
Escape all double quotes.
</para>
</callout>
<callout arearefs="sed2">
<para>
Add the string '$content .= "' at the start of every line.
</para>
</callout>
<callout arearefs="sed3">
<para>
Add the string '";' at the end of every line.
</para>
</callout>
<callout arearefs="sed4">
<para>
Add a newline \n at the end of each JS line.
</para>
</callout>
</calloutlist>
<para>You can put them in a file, sedscr,<indexterm><primary>sedscr</primary></indexterm> and tell sed to read sedscr for commands, while editing the original Javascript file (javascript):</para><screen><![CDATA[sed -f sedscr javascript > block-Javascript.php
]]></screen><para>Of course, you can use vi (<xref linkend="vi">) too - see <xref linkend="javascript-php"> for a similar example - or just do the substitutions manually. The examples in this section demonstrate what you have to do (see also <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=379">Javascript in a <application>PHP-Nuke</application> block</ulink>):</para><itemizedlist><listitem><para>How to create a Hello World block (<xref linkend="create-hello-world-block">),</para></listitem><listitem><para>How to create a fade block (<xref linkend="create-fade-block">),</para></listitem><listitem><para>How to create a Help Center Live block (<xref linkend="create-help-center-live-block">).</para></listitem></itemizedlist><sect2 id="create-hello-world-block"><title>How to create a Hello World block</title><para>
<figure id="fig-hello-world-javascript">
<title>
Hello World block with Javascript.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1160;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1160;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1160;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1160;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Hello World block with Javascript.</phrase>
</textobject>
<caption>
<para>Hello World block with Javascript.</para>
</caption>
</mediaobject>
</figure>
</para><para>We will start with a very simple block,<indexterm><primary>block</primary></indexterm> one that just displays &ldquo;Hello World&rdquo;. Once you get the idea, you will be able to construct any Javascript block<indexterm><primary>block</primary></indexterm> for <application>PHP-Nuke</application> - they all follow the same rules.<indexterm><primary>rules</primary></indexterm></para><para>We will keep the Javascript code in a separate file, say hello-world.php,<indexterm><primary>hello-world.php</primary></indexterm> in the <application>PHP-Nuke</application> includes directory. The includes directory is a natural place for it, because it also contains the javascript.<indexterm><primary>javascript</primary></indexterm>php file (see <xref linkend="javascript-php">). You can use the javascript.<indexterm><primary>javascript</primary></indexterm>php file to store your own Javascript functions (as shown in <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=379">Javascript in a <application>PHP-Nuke</application> block</ulink>), but for this simple example, hello-world.php is more than enough. It contains only a few lines:</para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[echo '
]]><![CDATA[document.write("Hello World!");
]]><![CDATA[';
]]><![CDATA[
]]><![CDATA[?>
]]></screen><para>Now, create a block,<indexterm><primary>block</primary></indexterm> block-Hello_World.php, in the blocks folder that contains:</para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[if (eregi("block-Hello_World.php",$_SERVER[PHP_SELF])) {
]]><![CDATA[ Header("Location: index.php");
]]><![CDATA[ die();
]]><![CDATA[}
]]><![CDATA[$content.="<center><script language=\"JavaScript\"
]]><![CDATA[src=\"includes/hello-world.php\"></script></center></b>";
]]><![CDATA[
]]><![CDATA[?>
]]></screen><para>As you can see, block-Hello_World.php loads the hello-world.php from the includes<indexterm><primary>includes</primary></indexterm> folder as a Javascript code. hello-world.php,<indexterm><primary>hello-world.php</primary></indexterm> in turn, is executed and echoes the document.write command in the HTML file that is sent to the client's browser. When a the browser receives it (and has Javascript enabled), executes the code writing the &quot;Hello World&quot; message in the place it was called - in the Hello World block.<indexterm><primary>block</primary></indexterm></para><para>Using this technique, you can create blocks that are very rich in functionality<indexterm><primary>functionality</primary></indexterm> - just echo their code with a <acronym>PHP</acronym> file and call that file as Javascript<indexterm><primary>Javascript</primary></indexterm> code from the block.<indexterm><primary>block</primary></indexterm> See <xref linkend="create-help-center-live-block"> for a non-trivial example.</para></sect2>
<sect2 id="create-fade-block"><title>How to create a fade block</title><para>So you have seen this cool fade effect on a site and you decided to incorporate<indexterm><primary>corporate</primary></indexterm> it in a <application>PHP-Nuke</application> block on your site too? I mean that effect that makes the image fade gradually away, when you pass over it with the mouse cursor - and comes again gradually back the next time you revisit it with the mouse cursor. Before you plunge into this, consider that it is just an effect - and one that will work only with Internet Explorer.<indexterm><primary>Explorer</primary></indexterm> If you still feel you must have it, here is the <application>PHP-Nuke</application> block that demonstrates this fade effect:</para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[if (eregi("block-Fade.php",$PHP_SELF)) {
]]><![CDATA[Header("Location: index.php");
]]><![CDATA[die();
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[$content .= "<script> \n";
]]><![CDATA[$content .= "\n";
]]><![CDATA[$content .= "/* \n";
]]><![CDATA[$content .= "Gradual-Highlight Image Script II- \n";
]]><![CDATA[$content .= "By J. Mark Birenbaum (birenbau@ugrad.cs.ualberta.ca) \n";
]]><![CDATA[$content .= "Permission granted to Dynamicdrive.com to feature script in archive \n";
]]><![CDATA[$content .= "For full source to script, visit http://dynamicdrive.com \n";
]]><![CDATA[$content .= "*/ \n";
]]><![CDATA[$content .= "\n";
]]><![CDATA[$content .= "nereidFadeObjects = new Object(); \n";
]]><![CDATA[$content .= "nereidFadeTimers = new Object(); \n";
]]><![CDATA[$content .= "\n";
]]><![CDATA[$content .= "/* object - image to be faded (actual object, not name); \n";
]]><![CDATA[$content .= "* destop - destination transparency level (ie 80, for mostly solid) \n";
]]><![CDATA[$content .= "* rate - time in milliseconds between trasparency changes (best under 100) \n";
]]><![CDATA[$content .= "* delta - amount of change each time (ie 5, for 5% change in transparency) \n";
]]><![CDATA[$content .= "*/ \n";
]]><![CDATA[$content .= "\n";
]]><![CDATA[$content .= "function nereidFade(object, destOp, rate, delta){ \n";
]]><![CDATA[$content .= "if (!document.all) \n";
]]><![CDATA[$content .= "return \n";
]]><![CDATA[$content .= "if (object != \"[object]\"){ //do this so I can take a string too \n";
]]><![CDATA[$content .= "setTimeout(\"nereidFade(\"+object+\",\"+destOp+\",\"+rate+\",\"+delta+\")\",0); \n";
]]><![CDATA[$content .= "return; \n";
]]><![CDATA[$content .= "} \n";
]]><![CDATA[$content .= "\n";
]]><![CDATA[$content .= "clearTimeout(nereidFadeTimers[object.sourceIndex]); \n";
]]><![CDATA[$content .= "\n";
]]><![CDATA[$content .= "diff = destOp-object.filters.alpha.opacity; \n";
]]><![CDATA[$content .= "direction = 1; \n";
]]><![CDATA[$content .= "if (object.filters.alpha.opacity > destOp){ \n";
]]><![CDATA[$content .= "direction = -1; \n";
]]><![CDATA[$content .= "} \n";
]]><![CDATA[$content .= "delta=Math.min(direction*diff,delta); \n";
]]><![CDATA[$content .= "object.filters.alpha.opacity+=direction*delta; \n";
]]><![CDATA[$content .= "\n";
]]><![CDATA[$content .= "if (object.filters.alpha.opacity != destOp){ \n";
]]><![CDATA[$content .= "nereidFadeObjects[object.sourceIndex]=object; \n";
]]><![CDATA[$content .= "nereidFadeTimers[object.sourceIndex]=setTimeout
]]><![CDATA[(\"nereidFade(nereidFadeObjects[\"+object.sourceIndex+\"],\"+destOp+\",
]]><![CDATA[\"+rate+\",\"+delta+\")\",rate);\n";
]]><![CDATA[$content .= "\n";
]]><![CDATA[$content .= "} \n";
]]><![CDATA[$content .= "} \n";
]]><![CDATA[$content .= "\n";
]]><![CDATA[$content .= "</script> \n";
]]><![CDATA[$content .= "<center><img src=\"images/xxx.png\"
]]><![CDATA[style=\"filter:alpha(opacity=10)\" onmouseover=\"nereidFade(this,100,30,5)\"
]]><![CDATA[onmouseout=\"nereidFade(this,10,50,5)\"></center>";
]]><![CDATA[
]]><![CDATA[?>
]]></screen><para>This is an adaptation of the <ulink url="http://www.dynamicdrive.com/dynamicindex4/highlightgrad2.htm">Dynamic Highlight II Script</ulink>, by J Mark Birenbaum,<indexterm><primary>Birenbaum</primary></indexterm> that just appends the Javascript code in the $content variable of a <application>PHP-Nuke</application> block.<indexterm><primary>block</primary></indexterm> You can adjust some parameters, such as the transparency level, the time between trasparency changes and amount of change each time - see the comments<indexterm><primary>comments</primary></indexterm> in the script's code. You should of course at least adapt the image source file (images/xxx.png<indexterm><primary>png</primary></indexterm> in the code) to your situation.</para></sect2>
<sect2 id="create-help-center-live-block"><title>How to create a Help Center Live block</title><para>We will now move on to consider a block that can integrate the whole functionality of a Help Center:<indexterm><primary>Center</primary></indexterm> the Help Center Live block for <application>PHP-Nuke</application>. <ulink url="http://www.helpcenterlive.com">Help Center Live</ulink> is an Open Source Application that is distributed under the <acronym>GNU</acronym> Genreal Public License (GPL). It helps you build a real support department for your business.<indexterm><primary>business</primary></indexterm> With Help Center Live you can:</para><itemizedlist><listitem><para>Create online accounts for your departments.</para></listitem><listitem><para>Create online accounts for your support operators and assign them to departments.</para></listitem><listitem><para>Create FAQs for your customers.<indexterm><primary>customers</primary></indexterm></para></listitem><listitem><para>If an operator is online, he can see which hosts currently view the company's page and can initiate chat sessions with those hosts.</para></listitem><listitem><para>If someone from a support department is online (has logged in Help Center<indexterm><primary>Center</primary></indexterm> Live), the visitors browsing the company's page can see this and initiate a chat session with that support person. Thus, a customer can directly contact support personnel and seek a solution to his problem.</para></listitem><listitem><para>At the end of the chat session,<indexterm><primary>session</primary></indexterm> a transcript of the session can be sent to the participants, at e-mail addresses of their choice. </para></listitem><listitem><para>If nobody from the support department(s) is online, the visitor still has the possibility to issue a trouble ticket.<indexterm><primary>ticket</primary></indexterm></para></listitem><listitem><para>Trouble tickets are tracked through a database and there exists a sophisticated<indexterm><primary>sophisticated</primary></indexterm> backend for dealing with them.</para></listitem></itemizedlist><para>How can you incorporate all this functionality into your <application>PHP-Nuke</application> site?</para><para>At first, you must install Help Center Live on our site, or, if we only want to test it, local system.<indexterm><primary>system</primary></indexterm> For this, download the package from <ulink url="http://www.helpcenterlive.com">Help Center Live</ulink> and extract its contents into some folder of your web root,<indexterm><primary>root</primary></indexterm> say under /helpcenter. Then you must edit the config.<indexterm><primary>config</primary></indexterm>php file in the inc directory of that folder with the decent text editor (<xref linkend="editing-PHP-Nuke-files">) of your choice. There are various parameters you can set up there, but the most important are the $URL_* ones</para><screen><![CDATA[$URL_site = "midas";
]]><![CDATA[$URL_dir = "/helpcenter/";
]]><![CDATA[$URL_maindir = "http://midas/helpcenter";
]]><![CDATA[$URL_secure = 0;
]]></screen><para>as well as the DB_* ones:</para><screen><![CDATA[$DB_host = "localhost";
]]><![CDATA[$DB_user = "db user here";
]]><![CDATA[$DB_pass = "db password here";
]]><![CDATA[$DB_name = "db name here";
]]><![CDATA[$DB_prefix = "prefix here";
]]><![CDATA[$DB_pconnect = 0;
]]></screen><para>The $DB_host, $DB_user, $DB_pass and $DB_name variables could be the same as the $dbhost, $dbuser,<indexterm><primary>dbuser</primary></indexterm> $dbpass and $dbname variables in config.php respectively (see <xref linkend="config-php-file">), although not necessarily so. </para><tip>
<title>
Terminate the DB_prefix with an underscore!
</title>
<para>
If you use a $DB_prefix, make sure it ends in an underscore (_), otherwise it will be directly concatenated with the table names, rendering them difficult to tell apart.
</para>
</tip>
<para>The $URL_site, $URL_dir and $URL_secure variables are only used in calls to the <ulink url="http://www.php.net/manual/en/function.setcookie.php">PHP setcookie() function</ulink>:</para><screen><![CDATA[setcookie("Help Center LiveUser", $INFO_username, $time, $URL_dir, $URL_site, $URL_secure);
]]></screen><para>Calls to setcookie() like the above are scattered throughout the code - <xref linkend="tab-Help-Center-Live-setcookie"> lists all files and lines containing such calls. If you experience the infamous login loop problem, it is probably because the setcookie() function was not able to set the cookie on the client. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_frown.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_frown.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_frown.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_frown.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
<para><table id="tab-Help-Center-Live-setcookie"><title>Help Center Live: setcookie() calls</title><tgroup cols="2" colsep="1" rowsep="1">
<colspec colname="col0" align="left">
<colspec colname="col1" align="left">
<tbody>
<row>
<entry align="left" valign="top"><para>File</para></entry>
<entry align="left" valign="top"><para>setcookie() call</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>cp/logout.php</para></entry>
<entry align="left" valign="top"><para>setcookie(&quot;HelpCenterLiveOperator&quot;, $LOGIN_username, $time, $URL_dir, $URL_site, $URL_secure);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>cp/logout.php</para></entry>
<entry align="left" valign="top"><para>setcookie(&quot;HelpCenterLivePassword&quot;, $LOGIN_password, $time, $URL_dir, $URL_site, $URL_secure);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>cp/login.php</para></entry>
<entry align="left" valign="top"><para>setcookie(&quot;HelpCenterLiveOperator&quot;, $LOGIN_username, $time, $URL_dir, $URL_site, $URL_secure);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>cp/login.php</para></entry>
<entry align="left" valign="top"><para>setcookie(&quot;HelpCenterLivePassword&quot;, $LOGIN_password, $time, $URL_dir, $URL_site, $URL_secure);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>lh/live_request.php</para></entry>
<entry align="left" valign="top"><para>setcookie(&quot;HelpCenterLiveGuest&quot;, $REQUEST_name, $time, $URL_dir, $URL_site, $URL_secure);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>lh/live_request.php</para></entry>
<entry align="left" valign="top"><para>setcookie(&quot;HelpCenterLiveGuest&quot;, $REQUEST_delname, $deltime, $URL_dir, $URL_site, $URL_secure);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>lh/live_request.php</para></entry>
<entry align="left" valign="top"><para>setcookie(&quot;HelpCenterLiveGuest&quot;, $REQUEST_name, $time, $URL_dir, $URL_site, $URL_secure);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>lh/live_mail.php</para></entry>
<entry align="left" valign="top"><para>setcookie(&quot;HelpCenterLiveUser&quot;, $LOGIN_username, $time, $URL_dir, $URL_site, $URL_secure);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>lh/live_mail.php</para></entry>
<entry align="left" valign="top"><para>setcookie(&quot;HelpCenterLivePass&quot;, $LOGIN_password, $time, $URL_dir, $URL_site, $URL_secure);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>tt/user_register.php</para></entry>
<entry align="left" valign="top"><para>setcookie(&quot;Help Center LiveUser&quot;, $REGISTER_username, $time, $URL_dir, $URL_site, $URL_secure);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>tt/user_register.php</para></entry>
<entry align="left" valign="top"><para>setcookie(&quot;Help Center LivePass&quot;, $REGISTER_password, $time, $URL_dir, $URL_site, $URL_secure);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>tt/user_login.php</para></entry>
<entry align="left" valign="top"><para>setcookie(&quot;HelpCenterLiveUser&quot;, $LOGIN_username, $time, $URL_dir, $URL_site, $URL_secure);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>tt/user_login.php</para></entry>
<entry align="left" valign="top"><para>setcookie(&quot;HelpCenterLivePass&quot;, $LOGIN_password, $time, $URL_dir, $URL_site, $URL_secure);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>tt/user_logout.php</para></entry>
<entry align="left" valign="top"><para>setcookie(&quot;HelpCenterLiveUser&quot;, $LOGIN_username, $time, $URL_dir, $URL_site, $URL_secure);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>tt/user_logout.php</para></entry>
<entry align="left" valign="top"><para>setcookie(&quot;HelpCenterLivePass&quot;, $LOGIN_password, $time, $URL_dir, $URL_site, $URL_secure);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>tt/user_info.php</para></entry>
<entry align="left" valign="top"><para>setcookie(&quot;Help Center LiveUser&quot;, $INFO_username, $time, $URL_dir, $URL_site, $URL_secure);</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>tt/user_info.php</para></entry>
<entry align="left" valign="top"><para>setcookie(&quot;Help Center LivePass&quot;, $INFO_password, $time, $URL_dir, $URL_site, $URL_secure);</para></entry>
</row>
</tbody>
</tgroup></table></para><para>This happens if, for example, you are installing Help Center Live locally, and the host name for $URL_site is taken from a hosts file and not from DNS.<indexterm><primary>DNS</primary></indexterm> One way to get around this is to change all calls to setcookie() listed in <xref linkend="tab-Help-Center-Live-setcookie"> and take out the last two parameters, $URL_site and $URL_secure, as in the following example:</para><screen><![CDATA[setcookie("Help Center LiveUser", $INFO_username, $time, $URL_dir);
]]></screen><para>After the installation of Help Center Live, you can point your browser to the address you entered for $URL_maindir (http://midas/helpcenter, in our example) and, after a successful login,<indexterm><primary>login</primary></indexterm> you will be presented with the main screen (<xref linkend="fig-help-center-live-main">).</para><para>
<figure id="fig-help-center-live-main">
<title>
Help Center Live: Main screen.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1161;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1161;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1161;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1161;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Help Center Live: Main screen.</phrase>
</textobject>
<caption>
<para>Help Center Live: Main screen.</para>
</caption>
</mediaobject>
</figure>
</para><para>Now, create a <application>PHP-Nuke</application> block that uses the method of our Hello World example in <xref linkend="create-hello-world-block"> to incorporate Help Center Live's functionality:<indexterm><primary>functionality</primary></indexterm></para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[if (eregi("block-Online_Support.php",$_SERVER[PHP_SELF])) {
]]><![CDATA[ Header("Location: index.php");
]]><![CDATA[ die();
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[$content.="<center><script language=\"JavaScript\"
]]><![CDATA[src=\"http://midas/helpcenter/lh/live.php\"></script></center></b>";
]]><![CDATA[
]]><![CDATA[?>
]]></screen><para>We named the block above &quot;block-Online_Support&quot;<indexterm><primary>block-Online_Support</primary></indexterm>, but of course you can use whatever title you like, as long as it is passed as the &quot;needle&quot; string to the eregi() function of the block.<indexterm><primary>block</primary></indexterm> The main code consists of only one line, which inserts a Javascript code, whose source file is the lh/live.php <acronym>PHP</acronym> script of Help Center Live. We did the same in <xref linkend="create-hello-world-block"> to output a Hello World message, but now, this simple line opens a whole world of possibilities for our <application>PHP-Nuke</application> page! Let's see what happens when we activate the Online Support block we just created:</para><para>As long as all Help Center operators are logged off, the block will display a &ldquo;Live Support is Offline&rdquo; message, as in <xref linkend="fig-help-center-live-block-offline">.</para><para>
<figure id="fig-help-center-live-block-offline">
<title>
Help Center Live block: Live Support is Offline.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1162;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1162;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1162;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1162;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Help Center Live block: Live Support is Offline.</phrase>
</textobject>
<caption>
<para>Help Center Live block: Live Support is Offline.</para>
</caption>
</mediaobject>
</figure>
</para><para>In this case,<indexterm><primary>case</primary></indexterm> a click on the arrow in the block's inside will open a window that gives the customer the possibility to enter a trouble ticket (<xref linkend="fig-help-center-live-block-trouble-ticket">). The window also offers a link to the FAQ and offers the choice to refer to an existing trouble ticket or create a new one.</para><para>
<figure id="fig-help-center-live-block-trouble-ticket">
<title>
Help Center Live block: Creating a trouble ticket.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1163;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1163;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1163;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1163;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Help Center Live block: Creating a trouble ticket.</phrase>
</textobject>
<caption>
<para>Help Center Live block: Creating a trouble ticket.</para>
</caption>
</mediaobject>
</figure>
</para><para>On the other side, if some support operator is online <emphasis>and has launched the request monitor<indexterm><primary>monitor</primary></indexterm></emphasis> (which opens a window for the operator,<indexterm><primary>operator</primary></indexterm> displaying the live connections he is currently maintaining), the block will display it with a &ldquo;Live Support is Online!&rdquo; message (<xref linkend="fig-help-center-live-block-online">).</para><para>
<figure id="fig-help-center-live-block-online">
<title>
Help Center Live block: Live Support is Online.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1164;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1164;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1164;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1164;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Help Center Live block: Live Support is Online.</phrase>
</textobject>
<caption>
<para>Help Center Live block: Live Support is Online.</para>
</caption>
</mediaobject>
</figure>
</para><para>The request monitor,<indexterm><primary>monitor</primary></indexterm> on the operator's side, will display all hosts that are currently viewing the <application>PHP-Nuke</application> page with the Online Support block showing the &ldquo;Live Support is Online!&rdquo; message (<xref linkend="fig-help-center-live-block-request-monitor">). In other words,<indexterm><primary>words</primary></indexterm> both users and operators are informed of each other's online presence.</para><para>
<figure id="fig-help-center-live-block-request-monitor">
<title>
Help Center Live block: Request monitor for the operator.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1165;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1165;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1165;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1165;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Help Center Live block: Request monitor for the operator.</phrase>
</textobject>
<caption>
<para>Help Center Live block: Request monitor for the operator.</para>
</caption>
</mediaobject>
</figure>
</para><para>Now - and this adds a tremendous value to that tiny block we just created - each side can initiate an online chat with the other part:</para><para>The operator can click on the &ldquo;Initiate&rdquo; link and, after selecting the aproppriate department, initiate a chat with the selected user. The user will get pop-up window, notifying him of the operator's wish for a chat (<xref linkend="fig-help-center-live-block-user-notify">). The user can then decide whether to accept or decline the chat request.</para><para>
<figure id="fig-help-center-live-block-user-notify">
<title>
Help Center Live block: User notification of the operator's chat request.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1166;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1166;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1166;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1166;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Help Center Live block: User notification of the operator's chat request.</phrase>
</textobject>
<caption>
<para>Help Center Live block: User notification of the operator's chat request.</para>
</caption>
</mediaobject>
</figure>
</para><para>On the user's side, everybody can click on the arrow besides the &ldquo;Online!&rdquo; message in the Online Support block.<indexterm><primary>block</primary></indexterm> This will initiate a chat request on behalf of the user (<xref linkend="fig-help-center-live-block-user-request">). The operator will get a pop-up window notifying him of the user's request, which he can accept or decline as well.</para><para>
<figure id="fig-help-center-live-block-user-request">
<title>
Help Center Live block: User chat request.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1167;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1167;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1167;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1167;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Help Center Live block: User chat request.</phrase>
</textobject>
<caption>
<para>Help Center Live block: User chat request.</para>
</caption>
</mediaobject>
</figure>
</para><para>Either way, initiating from the operator's or user's side, a chat session<indexterm><primary>session</primary></indexterm> starts between the two, hopefully leading to the solution of the user's problem. A transcript of the chat can be sent to an e-mail address of the participant's choice for future reference.</para><para>This completes our brief review of Help Center Live's features.<indexterm><primary>features</primary></indexterm> If you have a look at the code of the Online Support block above and the code of the Hello World block in <xref linkend="create-hello-world-block">, you will see that they both use the same method to incorporate functionality<indexterm><primary>functionality</primary></indexterm> in a <application>PHP-Nuke</application> block through Javascript.<indexterm><primary>Javascript</primary></indexterm> The method is the same, but what a huge difference in functionality! There, a simple &ldquo;Hello World&rdquo; output - here, a full-featured Help Center! This demonstrates the broad spectrum of possibilities that a simple line like</para><screen><![CDATA[$content.="<center><script language=\"JavaScript\"
]]><![CDATA[src=\"Some <acronym>PHP</acronym> script\"></script></center></b>";
]]></screen><para>can offer, when used intelligently in a <application>PHP-Nuke</application> block with Javascript.<indexterm><primary>Javascript</primary></indexterm></para><note>
<title>
Help Center Live is looking for a sponsor!
</title>
<para>
HCL is getting well over a million hits per month and its on a huge increase keeping in mind that Fantastico now has HCL as a featured script for install. Mike, the developer of HCL, offers it under the GPL - however, he is looking for sponsor to help him continue its development for free and cope with the ever-increasing hosting fees and other expenses. Please contact Mike, if you are interested and serious about sponsoring HCL.
</para>
</note>
</sect2>
</sect1>
<sect1 id="flash-php-nuke-blocks"><title>How to display Flash in <application>PHP-Nuke</application> blocks</title><para>To show Flash in a <application>PHP-Nuke</application> block,<indexterm><primary>block</primary></indexterm> you simply have to include the appropriate HTML code in the $content variable. Since the HTML code is something like</para><screen><![CDATA[<object classid=\"clsid:D27CDB6E-AE6D-11cf-96B8-444553540000\"
]]><![CDATA[codebase=\"http://download.macromedia.com/pub/shockwave/cabs/
]]><![CDATA[flash/swflash.cab#version=6,0,29,0\" width=\"350\" height=\"100\">
]]><![CDATA[<param name=\"movie\" value=\"yourMovie.swf\">
]]><![CDATA[<param name=quality value=high>
]]><![CDATA[<embed src=\"yourMovie.swf\" quality=high
]]><![CDATA[pluginspage=\"http://www.macromedia.com/shockwave/
]]><![CDATA[download/index.cgi?P1_Prod_Version=ShockwaveFlash\"
]]><![CDATA[type=\"application/x-shockwave-flash\"
]]><![CDATA[width=\"350\" height=\"100\"></embed>
]]><![CDATA[</object>
]]></screen><para>the <application>PHP-Nuke</application> block code should be something like</para><screen><![CDATA[$content = "<object classid=\"clsid:D27CDB6E-AE6D-11cf-96B8-444553540000\"
]]><![CDATA[codebase=\"http://download.macromedia.com/pub/shockwave/cabs/
]]><![CDATA[flash/swflash.cab#version=6,0,29,0\" width=\"350\" height=\"100\"> "
]]><![CDATA[."<param name=\"movie\" value=\"yourMovie.swf\"> "
]]><![CDATA[."<param name=quality value=high> "
]]><![CDATA[."<embed src=\"yourMovie.swf\" quality=high
]]><![CDATA[pluginspage=\"http://www.macromedia.com/shockwave/
]]><![CDATA[download/index.cgi?P1_Prod_Version=ShockwaveFlash\"
]]><![CDATA[type=\"application/x-shockwave-flash\"
]]><![CDATA[width=\"350\" height=\"100\"></embed>"
]]><![CDATA[."</object>";
]]></screen><para>See <xref linkend="PHP-Nuke-header-display-flash-object"> on how to display Flash in the <application>PHP-Nuke</application> header, like a banner.<indexterm><primary>banner</primary></indexterm></para></sect1>
<sect1 id="advertisements-in-php-nuke-blocks"><title>How to show advertisements in <application>PHP-Nuke</application> blocks</title><para>Advertisements are a popular source of revenue for webmasters. It doesn't take long until the young webmaster feels attracted to the sirene call of affiliate programs, banners or context relevant advertising. </para><para>Advertisements are often created through the use of a Javascript function,<indexterm><primary>function</primary></indexterm> called at the right place in the HTML code. We have already treated the subject of Javascript in <application>PHP-Nuke</application> blocks (see <xref linkend="javascript-in-php-nuke-blocks">) and modules (see <xref linkend="javascript-in-php-nuke-modules">) and seen that Javascript does not pose any special problems with <application>PHP-Nuke</application>. However, due to the increasing popularity of Google's <ulink url="https://www.google.com/adsense/overview">AdSense</ulink> program, there has been an increasing demand for ready-to-use solutions in the <application>PHP-Nuke</application> field. The following code examples should be seen as representative examples of how such advertising functionality can be incorporated in <application>PHP-Nuke</application> blocks. You can use them as starting point for <ulink url="http://www.content.overture.com/d/USm/ps/cm.jhtml">similar advertising solutions</ulink>, as offered by today's modern search engines or affiliate programs.</para><tip>
<title>
Ready-to-use Google AdSense Block
</title>
<para>
If you don't feel like writing your own Google AdSense block, just use a ready-made one! Go to <ulink url="http://home.vie4life.com/downloads-cat-13.html">http://home.vie4life.com/downloads-cat-13.html</ulink> and download a ready-to-use AdSense block.
</para>
</tip>
<para>Create a block called block-AdSense.<indexterm><primary>AdSense</primary></indexterm>php and add the following in the file:</para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[if (eregi("block-AdSense.php",$PHP_SELF)) {
]]><![CDATA[ Header("Location: index.php");
]]><![CDATA[ die();
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[?>
]]><![CDATA[
]]><![CDATA[<script language="JavaScript">
]]><![CDATA[<!--
]]><![CDATA[google_ad_client = 'your client-number';
]]><![CDATA[google_ad_width = 468;
]]><![CDATA[google_ad_height = 60;
]]><![CDATA[google_ad_format = '468X60_as';
]]><![CDATA[google_color_border = "E5E5E5";
]]><![CDATA[google_color_bg = "E5E5E5";
]]><![CDATA[google_color_link = "336699";
]]><![CDATA[google_color_url = "000000";
]]><![CDATA[google_color_text = "000000";
]]><![CDATA[// -->
]]><![CDATA[</script>
]]><![CDATA[
]]><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[$content .= "<center><script language=\"JavaScript\"
]]><![CDATA[src=\"http://pagead2.googlesyndication.com/pagead/show_ads.js\">";
]]><![CDATA[$content .= "</script></center>";
]]><![CDATA[
]]><![CDATA[?>
]]></screen><important>
<title>
Don't forget:
</title>
<para>
Add your Google client number in the script.
</para>
</important>
<para>Activate the AdSense block in your administration panel (see <xref linkend="admin-management">) by clicking on the &ldquo;Blocks<indexterm><primary>Blocks</primary></indexterm>&rdquo; links and choosing it from the blocks list as a new block.<indexterm><primary>block</primary></indexterm> </para></sect1>
<sect1 id="display-images-php-nuke-blocks"><title>How to display images in <application>PHP-Nuke</application> blocks</title><para>Blocks offer a quick way to incorporate content in <application>PHP-Nuke</application>. They are happily used to display images,<indexterm><primary>images</primary></indexterm> since they can be placed anywhere in the three layout columns - and their position can be comfortably changed from the administration panel.<indexterm><primary>panel</primary></indexterm> A very common use of blocks in <application>PHP-Nuke</application> is to display <emphasis>dynamic<indexterm><primary>dynamic</primary></indexterm></emphasis> images,<indexterm><primary>images</primary></indexterm> i.e. images that change depending on some parameter of dynamic nature,<indexterm><primary>nature</primary></indexterm> most offen time: a daily quote, a daily weather forecast or a daily comic.<indexterm><primary>comic</primary></indexterm></para><para>Most of the time you will not be the original author of the quote, forecast<indexterm><primary>forecast</primary></indexterm> or comic.<indexterm><primary>comic</primary></indexterm> You will want to fetch this content from some popular source on the Internet.<indexterm><primary>Internet</primary></indexterm></para><important>
<title>
Before you proceed: think on copyright!
</title>
<para>
We will describe the tecnology that allows you to use somebody else's work to make your site more beautiful, attractive or informative. This almost certainly touches that person's copyright. Please take the time to read the admonition on copyright in <xref linkend="PHP-Nuke-comic-block">!
</para>
</important>
<para>PHP enables you to read a remote URL,<indexterm><primary>URL</primary></indexterm> store its whole content in one (!) variable, then search the contents of the variable for any regular expression (for regular expressions, see <xref linkend="regular-expressions">). We will use this technique to find out the filename of the <ulink url="http://www.userfriendly.org">User Friendly</ulink> daily comic strip,<indexterm><primary>strip</primary></indexterm> in order to display it in a <application>PHP-Nuke</application> block. This <ulink url="http://www.karakas-online.de/phpnuke/block-User_Friendly.tar">UserFriendly block</ulink> reads the <ulink url="http://www.userfriendly.org/static/">User Friendly daily cartoon page</ulink> line by line, searches for the pattern<indexterm><primary>pattern</primary></indexterm></para><screen><![CDATA[whatever<IMG ALT="Latest Strip"whateverSRC="imagefile">whatever
]]></screen><para>extracts the location of the image file (imagefile) from it and displays it in the block.<indexterm><primary>block</primary></indexterm> The <ulink url="http://www.karakas-online.de/myServices/showfile.php?highlight=userfriendly">PHP code of the User Friendly block </ulink> is a classic example of how you can do this &ldquo;scrapping<indexterm><primary>scrapping</primary></indexterm>&rdquo; in <acronym>PHP</acronym> (-Nuke):</para><screen>
<![CDATA[<?php]]>
<![CDATA[]]>
<![CDATA[if (eregi("block-User_Friendly.php",$PHP_SELF)) {]]> <co id="uf1">
<![CDATA[ Header("Location: index.php");]]>
<![CDATA[ die();]]>
<![CDATA[}]]>
<![CDATA[]]>
<![CDATA[]]>
<![CDATA[$ufurl = "http://www.userfriendly.org/static/";]]> <co id="uf2">
<![CDATA[$content = "<i>ufurl:</i> $ufurl<br>";]]>
<![CDATA[]]>
<![CDATA[$imagefile = "";]]> <co id="uf3">
<![CDATA[]]>
<![CDATA[]]>
<![CDATA[if (!($textfile = fopen( "$ufurl", "r"))) {]]> <co id="uf4">
<![CDATA[ $content .= "$ufurl<br> could not be opened<br>";]]> <co id="uf5">
<![CDATA[ die();]]>
<![CDATA[}]]>
<![CDATA[]]>
<![CDATA[while (!feof($textfile)) {]]> <co id="uf6">
<![CDATA[ $line = fgets($textfile, 1500); ]]> <co id="uf7">
<![CDATA[ if (eregi( ".*<IMG ALT=\"Latest Strip\".*SRC=\"(.*)\">.*", $line, $out)) {]]> <co id="uf8">
<![CDATA[ $imagefile = $out[1];]]> <co id="uf9">
<![CDATA[ break;]]>
<![CDATA[ }]]>
<![CDATA[}]]>
<![CDATA[]]>
<![CDATA[fclose($textfile);]]>
<![CDATA[]]>
<![CDATA[$content = "<p align=center>";]]>
<![CDATA[$content .= "<A HREF=\"http://www.userfriendly.org\" target=\"_blank\">
<IMG SRC=\"$imagefile\" alt=\"User Friendly by Illiad\"></A>";]]> <co id="uf10">
<![CDATA[]]>
<![CDATA[?>]]>
</screen>
<calloutlist>
<callout arearefs="uf1">
<para>
This is the standard check at the start of every <application>PHP-Nuke</application> block: if the name of the script, as it was called by the user, contains the full name of the block, then the user must have called the block directly. In this case we redirect him to the home page. As with modules, a direct call of a block not only will not work, it will also bypass all security measures of <application>PHP-Nuke</application> (see for example <xref linkend="security-audit">).
</para>
</callout>
<callout arearefs="uf2">
<para>
The URL of the remote page containing the dynamic image.
</para>
</callout>
<callout arearefs="uf3">
<para>
Initialization of the image filename.
</para>
</callout>
<callout arearefs="uf4">
<para>
We open the remote page for reading ("r"). This operation returns a "file handle", a unique identifier for the opened file, which is stored in $textfile.
</para>
</callout>
<callout arearefs="uf5">
<para>
If the opening operation failed, we output an error message in the content variable of the block and quit.
</para>
</callout>
<callout arearefs="uf6">
<para>
If the opening operation succeeded, we start reading the content of the remote page in a loop, line-by-line, until the end-of-file (eof) character is encountered.
</para>
</callout>
<callout arearefs="uf7">
<para>
We only read 1500 characters at a time. This is more than enough for our purposes.
</para>
</callout>
<callout arearefs="uf8">
<para>
This is where all the magic takes place! We search the line we just read for occurences of a regular expression. The expression itself means </para>
<screen>
whatever&lt;IMG ALT="Latest Strip"whateverSRC="imagefile"&gt;whatever
</screen>
<para>
where "whatever" may be any content, including space. The regular expression contains a subexpression in the place of the image filename. This results in the file name being stored in the $out array, as its first element.
</para>
</callout>
<callout arearefs="uf9">
<para>
We copy the first element the $out array to the $imagefile variable. By construction of the regular expression above, $imagefile now contains the image filename of the daily comic strip. We only have to display it!
</para>
</callout>
<callout arearefs="uf10">
<para>
We echo an image anchor using as source the filename we just "scrapped" from our source page. This displays the daily comic strip without fetching the image to our web server (hot linking!).
</para>
</callout>
</calloutlist>
<para>A similar technique is used in news aggregators,<indexterm><primary>aggregators</primary></indexterm> like the MyHeadlines module (see <xref linkend="PHP-Nuke-My-Headlines-module">), that &ldquo;scrap&rdquo; news sources for pieces of dynamic information that are not otherwise available (i.e. not available as RSS/RDF news feeds), see <ulink url="http://jmagar.com/modules/MyHeadlines/MyHeadlines/docs/headline_scraper.htm">Template Based Scraping</ulink>. For each source page, a regular expression is stored in a table. Its subexpressions will automatically store the dynamic information pieces that are of interest to us in the elements of some $out array. We would then only have to display those elements for each source.</para><tip>
<title>
Quod medicina aliis, aliis est acre venenum<footnote><para>One person's medicine is another's foul poison.</para></footnote>
</title>
<para>
If you are an artist whose images are being hot-linked with the above methods without your permission, you are certainly not excited. But don't despair! You can defend your work with a simple technique that requires only the Apache mod_rewrite module and a few lines in your .htaccess file. See <xref linkend="make-PHP-Nuke-hot-link-stealth">.
</para>
</tip>
<sect2 id="display-random-images-php-nuke-blocks"><title>How to display random images in <application>PHP-Nuke</application> blocks</title><para>We now move to a more advanced example of a <application>PHP-Nuke</application> block:<indexterm><primary>block</primary></indexterm> a block that displays random images.<indexterm><primary>images</primary></indexterm> Suppose you have a collection of images in a directory of your webserver<indexterm><primary>server</primary></indexterm> and would like to display a random image each time in a <application>PHP-Nuke</application> block.<indexterm><primary>block</primary></indexterm> Using PHP-Nuke's own positioning capabilities for blocks (in the administration<indexterm><primary>administration</primary></indexterm> panel,<indexterm><primary>panel</primary></indexterm> from the &ldquo;Blocks<indexterm><primary>Blocks</primary></indexterm>&rdquo; link, see <xref linkend="administration-functions">), you can achieve an almost arbitrary positioning of random images in your page - a functionality that could be used to display whatever visual content you like, ranging from a &ldquo;daily babe<indexterm><primary>babe</primary></indexterm>&rdquo; to a random skyscraper banner.<indexterm><primary>banner</primary></indexterm></para><para>To create a random image block for PHP-Nuke, proceed as follows (see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=12256">Random Picture Block</ulink>):</para><para>Make a script called block-RandomPics.php and put it in the blocks folder. The code for block-RandomPics.php is:</para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[$content="";
]]><![CDATA[
]]><![CDATA[if (eregi("block-RandomPics.php",$PHP_SELF)) {
]]><![CDATA[ Header("Location: index.php");
]]><![CDATA[ die();
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[// $whereimgs has to be in the Domain (like localhost area)
]]><![CDATA[// or put ../ in front of folder name
]]><![CDATA[$whereimgs = "../pictures";
]]><![CDATA[
]]><![CDATA[mt_srand((double)microtime()*1000000);
]]><![CDATA[$imgs = dir($whereimgs);
]]><![CDATA[while ($file = $imgs->read()) {
]]><![CDATA[ if (eregi("gif", $file) || eregi("jpg", $file)) {
]]><![CDATA[ $imglist .= "$file ";
]]><![CDATA[ }
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[closedir($imgs->handle);
]]><![CDATA[$imglist = explode(" ", $imglist);
]]><![CDATA[$a = sizeof($imglist)-2;
]]><![CDATA[$random = mt_rand(0, $a);
]]><![CDATA[$image = $imglist[$random];
]]><![CDATA[$asin = explode(".", $image);
]]><![CDATA[
]]><![CDATA[$content = "";
]]><![CDATA[$content .= "<center><a href=\"PicShow.php?show=".$whereimgs."/$image\">";
]]><![CDATA[$content .= "<img src=\"".$whereimgs."/$image\" border=\"0\"
]]><![CDATA[ width=\"120\" alt=\"\"><br><br>";
]]><![CDATA[$content .= "Click for full picture.</a><BR></center>";
]]><![CDATA[
]]><![CDATA[?>
]]></screen><para>The block-RandomPics.php block reads all .gif's and .jpg's from the $whereimgs directory into an array ($imglist), computes a random index between 0 and the maximum array index ($a) and uses the random index to select an image name from the array. It then writes some HTML code to display a thumbnail of 120 pixels width with a ling to the original picture. The link itself passes the show parameters on the URL as the concatenation<indexterm><primary>concatenation</primary></indexterm> of the $whereimgs directory and the random image name ($image) to a script we still have to write, PicShow.php.<indexterm><primary>PicShow.php</primary></indexterm></para><tip>
<title>
The right images path
</title>
<para>
Taking into account that block-RandomPics.php has to be located in the blocks folder, then, if your images folder is the folder &ldquo;pictures&rdquo; under the &ldquo;PHP-Nuke root&rdquo; directory (i.e. under the same directory where mainfile.php, index.php, config.php etc. are located), then you have to prepend a &ldquo;../&rdquo; to &ldquo;pictures&rdquo;, as we did in the code, assuming that you don't want to give an absolute, fully qualified URL there.
</para>
</tip>
<para>For PicShow.php,<indexterm><primary>PicShow.php</primary></indexterm> which is the script that will show the full image, we have to write code that behaves just like a standard <application>PHP-Nuke</application> module (but without any administration functions), so you can see it as an example of a minimal module:<indexterm><primary>module</primary></indexterm></para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[if (!isset($mainfile)) { include("mainfile.php"); }
]]><![CDATA[
]]><![CDATA[$index = 0;
]]><![CDATA[include("header.php");
]]><![CDATA[
]]><![CDATA[OpenTable();
]]><![CDATA[$sl = $show;
]]><![CDATA[
]]><![CDATA[echo "
]]><![CDATA[<center><h3><a href=\"javascript:history.back()\">Go back!<br><br>
]]><![CDATA[<img src=$sl border=\"2\"></a></h3>
]]><![CDATA[</center>";
]]><![CDATA[
]]><![CDATA[closetable();
]]><![CDATA[include("footer.php");
]]><![CDATA[
]]><![CDATA[?>
]]></screen></sect2>
</sect1>
<sect1 id="paypal-block-for-php-nuke"><title>How to display HTML forms in a block: Paypal</title><para>A lot of sites have a block,<indexterm><primary>block</primary></indexterm> asking for donations through <ulink url="https://www.paypal.com">PayPal</ulink>. It is easy to construct your own, all you need is get an account from PayPal,<indexterm><primary>PayPal</primary></indexterm> then construct an HTML form that contains your data,<indexterm><primary>data</primary></indexterm> for example:</para><screen><![CDATA[Help keep our web site online with a donation!
]]><![CDATA[<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
]]><![CDATA[<input type="hidden" name="cmd" value="_xclick">
]]><![CDATA[<input type="hidden" name="business" value="My email">
]]><![CDATA[<input type="hidden" name="item_name" value="My Homepage">
]]><![CDATA[<input type="hidden" name="amount" value="10.00">
]]><![CDATA[<input type="hidden" name="no_note" value="1">
]]><![CDATA[<input type="hidden" name="currency_code" value="USD">
]]><![CDATA[<input type="hidden" name="tax" value="0">
]]><![CDATA[<input type="image" src="https://www.paypal.com/images/x-click-but04.gif"
]]><![CDATA[ border="0"
]]><![CDATA[name="submit" alt="Make payments with PayPal - it"s fast, free and secure!">
]]><![CDATA[</form>
]]></screen><para>The meaning of the form fields is the following:</para><variablelist><varlistentry><term>cmd:
</term><listitem><para>Must be set to &quot;_xclick&quot; (required).</para></listitem></varlistentry><varlistentry><term>business:<indexterm><primary>business</primary></indexterm>
</term><listitem><para>This is your PayPal ID, or email address, where payments will be sent. This email address must be confirmed and linked to your Verified Business or Premier account. (required).</para></listitem></varlistentry><varlistentry><term>item_name:<indexterm><primary>item_name</primary></indexterm>
</term><listitem><para>Description of donation (maximum 127 characters). If omitted, donor will see a field in which they have the option of entering an Item Name (optional).</para></listitem></varlistentry><varlistentry><term>amount:
</term><listitem><para>The price or amount of the purchase, not including shipping, handling, or tax.<indexterm><primary>tax</primary></indexterm> If omitted, this value will be editable by the buyer at the time of purchase (optional).</para></listitem></varlistentry><varlistentry><term>no_note:
</term><listitem><para>Including a note with payment.<indexterm><primary>payment</primary></indexterm> If set to 1, your customer will not be prompted to include a note. If omitted or set to 0, your customer will be prompted to include a note (optional).</para></listitem></varlistentry><varlistentry><term>currency_code:
</term><listitem><para>The currency of the payment.<indexterm><primary>payment</primary></indexterm> Defines the currency in which the monetary variables (amount, shipping, shipping2, handling, tax) are denoted. Possible values are USD (U.S.<indexterm><primary>U.S.</primary></indexterm> Dollar), EUR (Euro), GBP (Pound Sterling), CAD (Canadian Dollar), JPY (Yen). If omitted, all monetary fields will be interpreted as U.S.<indexterm><primary>U.S.</primary></indexterm> Dollars (optional).</para></listitem></varlistentry><varlistentry><term>tax:<indexterm><primary>tax</primary></indexterm>
</term><listitem><para>Transaction-based tax override variable. Set to a flat tax amount you would like to apply to the transaction regardless of the buyer s location. If present, this value overrides any tax settings that may be set in the seller s Profile. If omitted, Profile tax settings (if any) will apply (optional).</para></listitem></varlistentry></variablelist><tip>
<title>
PayPal hyperlink variables
</title>
<para>
There are many more hyperlink variables that you can use in your PayPal block, covering all aspects of a donation transaction. You should consult the <ulink url="https://www.paypal.com/en_US/pdf/donations.pdf">PayPal Donations Manual</ulink>, to learn about all the possibilities!
</para>
</tip>
<para>
<figure id="fig-paypal1">
<title>
PayPal donation button
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1168;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1168;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1168;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1168;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>PayPal donation button</phrase>
</textobject>
<caption>
<para>PayPal donation button</para>
</caption>
</mediaobject>
</figure>
</para><para>Pasting the code above into your website would generate a button that looks like <xref linkend="fig-paypal1">. To create a block out of this HTML Form, all we have to do is add the obligatory check for the block name, transform all lines to strings and append them to the $content variable, taking care to escape all double quotes between the string quotes:<indexterm><primary>quotes</primary></indexterm></para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[if (eregi("block-Donations.php",$PHP_SELF)) {
]]><![CDATA[ Header("Location: index.php");
]]><![CDATA[ die();
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[$content = "Help keep our web site online with a donation!";
]]><![CDATA[$content .= "form action=\"https://www.paypal.com/cgi-bin/webscr\" method=\"post\">";
]]><![CDATA[$content .= "input type=\"hidden\" name=\"cmd\" value=\"_xclick\">";
]]><![CDATA[$content .= "input type=\"hidden\" name=\"business\" value=\"My email\">";
]]><![CDATA[$content .= "input type=\"hidden\" name=\"item_name\" value=\"My Homepage\">";
]]><![CDATA[$content .= "input type=\"hidden\" name=\"amount\" value=\"10.00\">";
]]><![CDATA[$content .= "input type=\"hidden\" name=\"no_note\" value=\"1\">";
]]><![CDATA[$content .= "input type=\"hidden\" name=\"currency_code\" value=\"USD\">";
]]><![CDATA[$content .= "input type=\"hidden\" name=\"tax\" value=\"0\">";
]]><![CDATA[$content .= "input type=\"image\" src=\"https://www.paypal.com/images/x-click-but04.gif\"
]]><![CDATA[ border=\"0\" name=\"submit\"
]]><![CDATA[ alt=\"Make payments with PayPal - it"s fast, free and secure!\">";
]]><![CDATA[$content .= "/form>";
]]><![CDATA[
]]><![CDATA[?>
]]><![CDATA[
]]></screen><para>Put the above code in a file called block-Donations.<indexterm><primary>ations</primary></indexterm>php in the blocks folder. Then, just activate and position the block from the blocks management link in the administration panel.<indexterm><primary>panel</primary></indexterm></para><para>
<figure id="fig-paypal2">
<title>
PayPal donation block.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1169;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1169;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1169;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1169;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>PayPal donation block.</phrase>
</textobject>
<caption>
<para>PayPal donation block.</para>
</caption>
</mediaobject>
</figure>
</para><para>Depending on your theme,<indexterm><primary>theme</primary></indexterm> the block will look as in <xref linkend="fig-paypal2">. You can experiment with various button images from the PayPal site. For more information on donations with PayPal,<indexterm><primary>PayPal</primary></indexterm> see the <ulink url="https://www.paypal.com/en_US/pdf/donations.pdf">PayPal Donations Manual</ulink>.</para></sect1>
</chapter>
<chapter id="creating-modules"><title>Creating modules</title><para>After having seen how to modify <application>PHP-Nuke</application> modules,<indexterm><primary>modules</primary></indexterm> we are in a position to try our skills at creating one - in this chapter we will show you how! We cover:</para><itemizedlist><listitem><para>Module structure (<xref linkend="module-structure">),</para></listitem><listitem><para>The rules to follow (<xref linkend="module-rules">),</para></listitem><listitem><para>Module creation, the public part (<xref linkend="module-public">),</para></listitem><listitem><para>Module creation, administrator part (<xref linkend="module-admin">),</para></listitem><listitem><para>How to include a HTML file in a <application>PHP-Nuke</application> module (<xref linkend="include-HTML-file-in-module">),</para></listitem><listitem><para>How to include a HTML file and its links in a <application>PHP-Nuke</application> module (<xref linkend="include-HTML-file-and-links-in-module">),</para></listitem><listitem><para>How to include a HTML file and its links using an iframe in a <application>PHP-Nuke</application> module<indexterm><primary>module</primary></indexterm> (<xref linkend="include-HTML-file-and-links-in-module-iframe">),</para></listitem><listitem><para>How to include a plain text file in a <application>PHP-Nuke</application> module (<xref linkend="include-plain-text-file-in-module">),</para></listitem><listitem><para>How to use Javascript in <application>PHP-Nuke</application> modules (<xref linkend="javascript-in-php-nuke-modules">),</para></listitem><listitem><para>How to create a Logout module (<xref linkend="create-logout-module">),</para></listitem><listitem><para>How to show advertisements in <application>PHP-Nuke</application> modules (<xref linkend="advertisements-in-php-nuke-modules">),</para></listitem><listitem><para>How to display HTML forms in a module (<xref linkend="HTML-forms-in-module">).</para></listitem></itemizedlist><sect1 id="module-structure"><title>Module structure </title><para>The <application>PHP-Nuke</application> modules are PHP-written applications that manage the central part of the site. For example, the &ldquo;News&rdquo;, &ldquo;Forum<indexterm><primary>Forum</primary></indexterm>&rdquo;, &ldquo;Members List&rdquo; etc. are all modules.<indexterm><primary>modules</primary></indexterm> Each module, based on it's complexity,<indexterm><primary>complexity</primary></indexterm> is structured using one part for the user's and another for the administrator,<indexterm><primary>administrator</primary></indexterm> in this case there are some contents we have to modify. It's all managed from the modules.<indexterm><primary>modules</primary></indexterm>php file which alone, carries out the job of authentication and management of the access rights on that module.<indexterm><primary>module</primary></indexterm> The modules.<indexterm><primary>modules</primary></indexterm>php file checks and verifies if the module was activated or not, and verifies the access rights. This saves us a lot of work because we don't have to insert these controls in every module we create.</para><para>We refer you to what is written in <xref linkend="module-management"> to be more exhaustive.</para><para>For example in the avantgo module, in order to load the index.<indexterm><primary>index</primary></indexterm>php file, it's enough to pass the module name to the parameter string, the file that will be searched for is index.php.<indexterm><primary>index.php</primary></indexterm></para><screen><![CDATA[modules.php?name=AvantGo
]]></screen><para>If instead we wanted to call a page different from the default index.php<indexterm><primary>index.php</primary></indexterm> (say, print.php), the string we will have to pass is :</para><screen><![CDATA[modules.php?name=AvantGo & file=print
]]></screen><para>That is the file variable with a value (print) that corresponds to the name of the file we want to load without the .php extension. </para><para>Inside of the folder modules/nameofmodule there is also a subfolder called &quot;language&quot;. In this fashion we manage in a simple and immediate way the multilanguage<indexterm><primary>multilanguage</primary></indexterm> functionality inside the modules.<indexterm><primary>modules</primary></indexterm></para><para>The rows modules.<indexterm><primary>modules</primary></indexterm>php work in this way:</para><itemizedlist><listitem><para>It includes the mainfile.php<indexterm><primary>mainfile.php</primary></indexterm></para></listitem><listitem><para>Verifies if the module is active</para></listitem><listitem><para>Verifies whether the string passes a file name different from index.php<indexterm><primary>index.php</primary></indexterm></para></listitem><listitem><para>Verifies the permissions of the module (whether everybody can see it, or only registered users, or only the administrator).</para></listitem></itemizedlist></sect1>
<sect1 id="module-rules"><title>Creating fully compatible modules: the rules to follow</title><para>For people who have a base knowledge of the <acronym>PHP</acronym> language it is very simple to construct a module.<indexterm><primary>module</primary></indexterm> Generally to create a <application>PHP-Nuke</application> module means:</para><itemizedlist><listitem><para>To create <acronym>PHP</acronym> files for the users, ie the public part of the site</para></listitem><listitem><para>To create an administrator interface </para></listitem><listitem><para>To verify that everything we have created is in keeping with the <application>PHP-Nuke</application> development rules.<indexterm><primary>rules</primary></indexterm></para></listitem></itemizedlist><para>But what about the development rules?<indexterm><primary>rules</primary></indexterm> </para><para>It is a good idea to stop on this point before continuing on to the programming part.</para><orderedlist><listitem><para>Rule:<indexterm><primary>Rule</primary></indexterm> the modules must be included in the folder modules/namemodule in the public part and the folder admin/modules in the administration part</para></listitem><listitem><para>Rule:<indexterm><primary>Rule</primary></indexterm> the main file of the module included in modules/nameofmodule must be called index.php<indexterm><primary>index.php</primary></indexterm></para></listitem><listitem><para>Rule: the tables in the php syntax are indicated by prefix.<indexterm><primary>prefix</primary></indexterm> For example Nuke pages will be indicated with &quot;$prefix.&quot;_pages, where $prefix<indexterm><primary>prefix</primary></indexterm> takes the value from the config.<indexterm><primary>config</primary></indexterm>php file which is nuke by default.</para></listitem><listitem><para>Rule:<indexterm><primary>Rule</primary></indexterm> the location of the images or links must start from the root of your html directory and not from the folder modules/nameofmodule because the files contained in it are included in a file placed in html's root directory that's called modules.<indexterm><primary>modules</primary></indexterm>php</para></listitem><listitem><para>Rule:<indexterm><primary>Rule</primary></indexterm> to manage the multilanguage function in an optimal way we have to create some text abstractions that we will insert in the files by making a folder called &ldquo;language&rdquo; inside the folder of the module.<indexterm><primary>module</primary></indexterm> Everything will then be automatically recalled. For example, if we need to create a module that we call Topolino (the Italian<indexterm><primary>Italian</primary></indexterm> name of Mickey Mouse) we must give the possibility to those who use the Italian interface to read &quot;Topolino&quot;<indexterm><primary>Topolino</primary></indexterm> and to those who use the English one to read &quot;Mickey Mouse&quot; ; -).</para></listitem></orderedlist><para>How do we do it?</para><para>First of all we create the folder &ldquo;language&rdquo; inside the folder modules/topolino We insert in this folder two php files that we will call lang-italian.php and lang-english.php We create an abstraction<indexterm><primary>abstraction</primary></indexterm> for topolino,<indexterm><primary>topolino</primary></indexterm> in the lang-italian.php it will be: </para><screen><![CDATA[define("_TOPO", "Topolino");
]]></screen><para>And in English it will be:</para><screen><![CDATA[define("_TOPO", "Mickey Mouse");
]]></screen><para>In this way inserting in the module the abstraction &quot;_TOPO&quot; this will be automatically replaced by Topolino in the Italian interface and by Mickey<indexterm><primary>key</primary></indexterm> Mouse in the English interface.<indexterm><primary>interface</primary></indexterm></para></sect1>
<sect1 id="module-public"><title>Module creation, the public part</title><para>We continue using the example of Topolino from <xref linkend="module-rules"> and create a very simple module that displays a GIF of Topolino with a list of 3 predefined names that are editable by the users. This is a nonsense module but it's simple enough to be understood by everybody. The DB we will use is MySQL,<indexterm><primary>MySQL</primary></indexterm> but the example, by changing some detail, works with all DB's. First of all let's see the skeleton of every module that we will construct:</para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[if (!eregi("modules.php", $PHP_SELF)) {
]]><![CDATA[ die ("You can't access this file directly...");
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[$index = 1;
]]><![CDATA[require_once("mainfile.php");
]]><![CDATA[
]]><![CDATA[$module_name = basename(dirname(__FILE__));
]]><![CDATA[get_lang($module_name);
]]><![CDATA[include("header.php");
]]><![CDATA[include("footer.php");
]]><![CDATA[
]]><![CDATA[?>
]]></screen><important>
<para>
Before making anything it's necessary to create a folder called "modules/Topolino", the file we have just created (with the other contents) must be called index.php and must stay in that folder.
</para>
</important>
<para>We create a table in the database called nuke_topolino that is structured in this way:</para><itemizedlist><listitem><para>idperson:<indexterm><primary>idperson</primary></indexterm> It is a cell that contains the id of person (int 11, primary)</para></listitem><listitem><para>nameperson: It is a cell that contains the names of the people (varchar 60)</para></listitem></itemizedlist><para>And we manually insert (by using PHPMyAdmin - see <xref linkend="phpmyadmin2"> - or an equivalent interface) the names of the 3 people we are interested in, see <xref linkend="fig-inserting-values"> (the module, for simplicity reasons doesn't allow you to add or to cancel<indexterm><primary>cancel</primary></indexterm> people but only editing those that already exist).</para><itemizedlist><listitem><para>Id 1: Topolino<indexterm><primary>Topolino</primary></indexterm></para></listitem><listitem><para>Id 2: Minnie<indexterm><primary>Minnie</primary></indexterm></para></listitem><listitem><para>Id 3: Pluto<indexterm><primary>Pluto</primary></indexterm></para></listitem></itemizedlist><para>
<figure id="fig-inserting-values">
<title>
PHPMyAdmin: inserting values
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1170;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1170;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1170;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1170;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>PHPMyAdmin: inserting values</phrase>
</textobject>
<caption>
<para>PHPMyAdmin: inserting values</para>
</caption>
</mediaobject>
</figure>
</para><note>
<para>
It's possible to include the footer at the end of every function. It's a solution that is a bit more complex because we must write more lines, but I have to stress how much alot of modules use it.
</para>
</note>
<para>Once that the table of the DB is ready we can begin to enjoy creating the code that will give us back our output. Our output will be one simple query with a cycle that will give back the values inserted in the database (the simplest thing in the world, Gosh!).</para><caution>
<title>
Attention!
</title>
<para>
To maintain the abstraction of the DB so that it can work on various database's in an independent way, we cannot use classic <acronym>PHP</acronym> syntax that is generally used by the MySQL addicted ; -), instead we must use the syntax illustrated in the file include/sql_layer.php
</para>
</caution>
<para>The query that we will compile will be structured in the following way:</para><screen><![CDATA[$resultpersons = sql_query("SELECT idperson, nameperson FROM "$prefix."_topolino", $dbi);
]]><![CDATA[
]]><![CDATA[for ($m=0; $m < sql_num_rows($resultpersons, $dbi); $m++){
]]><![CDATA[ list($idperson, $nameperson) = sql_fetch_row($resultpersons, $dbi);
]]><![CDATA[ echo "$idperson - $nameperson < br >";
]]><![CDATA[}
]]></screen><para>Very simple, isn't it? OK!, before passing to the administrator's interface<indexterm><primary>interface</primary></indexterm> for this module,<indexterm><primary>module</primary></indexterm> we will start to modify it with the intention of giving it a minimum style dignity.</para><para>I would propose:</para><itemizedlist><listitem><para>to insert the results in a table </para></listitem><listitem><para>to put a title to it and a description for the module.<indexterm><primary>module</primary></indexterm></para></listitem></itemizedlist><para>We can do this by rendering all of the module's compatible with the multilanguage system of PHP-Nuke: We define the abstractions that will compose the two phrases we need, in the file lang-english.php we have to insert:<indexterm><primary>insert</primary></indexterm></para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[define("_BENVETOPOMOD", "Topolino Module, Welcome!");
]]><![CDATA[define("_DESCRITOPOMOD", "This is an example module that
]]><![CDATA[serves to illustrate how a <application>PHP-Nuke</application> module is created");
]]><![CDATA[
]]><![CDATA[?>
]]></screen><para>Remember to insert a file called index.<indexterm><primary>index</primary></indexterm>htm in our language folder! We need it to protect the inside of that folder from undesired navigations.<indexterm><primary>navigations</primary></indexterm> We are nearly at the end of the frontend part, now we have to insert the stylistic part in the code that we have created and to assemble everything. We take two code pieces previously constructed (The initial one and the one created by us) and we join the stylistic modification:</para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[if (!eregi("modules.php", $PHP_SELF)){
]]><![CDATA[ die ("You can't access this rows directly...");
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[$index = 1;
]]><![CDATA[require_once("mainfile.php");
]]><![CDATA[
]]><![CDATA[$module_name = basename(dirname(__FILE__));
]]><![CDATA[get_lang($module_name);
]]><![CDATA[include("header.php");
]]><![CDATA[
]]><![CDATA[echo "<br>";
]]><![CDATA[echo""._BENVETOPOMOD."";
]]><![CDATA[echo "<br><br>";
]]><![CDATA[
]]><![CDATA[opentable();
]]><![CDATA[echo "<br>";
]]><![CDATA[echo""._DESCRITOPOMOD."";
]]><![CDATA[echo "<br><br>";
]]><![CDATA[$resultpersons = sql_query("SELECT idperson, nameperson
]]><![CDATA[ FROM ".$prefix."_topolino", $dbi);
]]><![CDATA[for ($m=0; $m < sql_num_rows($resultpersons, $dbi); $m++) {
]]><![CDATA[ list($idperson, $nameperson) = sql_fetch_row($resultpersons, $dbi);
]]><![CDATA[ echo "$idperson - $nameperson <br>";
]]><![CDATA[}
]]><![CDATA[closetable();
]]><![CDATA[
]]><![CDATA[include("footer.php");
]]><![CDATA[
]]><![CDATA[?>
]]></screen><para>We have only added text, some breaks for the headers and an &ldquo;Opentable();&rdquo; and a &ldquo;Closetable();&rdquo; to include the text. The result can be seen in <xref linkend="fig-example-module"></para><para>
<figure id="fig-example-module">
<title>
Example module.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1171;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1171;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1171;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1171;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Example module.</phrase>
</textobject>
<caption>
<para>Example module.</para>
</caption>
</mediaobject>
</figure>
</para></sect1>
<sect1 id="module-admin"><title>Module creation, administrator part</title><para>It's time to create the administration part of the module.<indexterm><primary>module</primary></indexterm> In this very simple module the only function that will work on the DB will be the one in which we can modify the text of one of the three languages that we have created. First of all, we have to create the files to insert in the folders:</para><itemizedlist><listitem><para>admin/case<indexterm><primary>admin/case</primary></indexterm></para></listitem><listitem><para>admin/links<indexterm><primary>admin/links</primary></indexterm></para></listitem><listitem><para>admin/modules </para></listitem></itemizedlist><para>It's important to remember how much we have just said in <xref linkend="directory-structure">:</para><variablelist><varlistentry><term>Admin:<indexterm><primary>Admin</primary></indexterm>
</term><listitem><para>contains 4 subdirectories (links, language, case, modules) that manage the various administration modules.<indexterm><primary>modules</primary></indexterm> The folder that holds the files is modules/admin/ .</para></listitem></varlistentry></variablelist><para>The folder admin/links<indexterm><primary>admin/links</primary></indexterm> instead says that the admin module must recall and position one language in admin for that determined module.<indexterm><primary>module</primary></indexterm></para><para>Example (Administration for the FAQ module):</para><screen><![CDATA[if (($radminsuper==1) OR ($radminfaq==1)) {
]]><![CDATA[adminmenu("admin.php?op=FaqAdmin ", "" _FAQ." ", "faq.gif");
]]><![CDATA[}
]]></screen><para>This module:<indexterm><primary>module</primary></indexterm></para><itemizedlist><listitem><para>Verifies the administration rights (This module can be set up so it can be viewed by the superadmin or an admin)</para></listitem><listitem><para>It passes a &ldquo;CASE<indexterm><primary>CASE</primary></indexterm>&rdquo; (op=FaqAdmin) that indicates to the admin.<indexterm><primary>admin</primary></indexterm>php file (that includes all the admin modules) the module to call, associates a value in order to translate the term &ldquo;FAQ<indexterm><primary>FAQ</primary></indexterm>&rdquo; and associates an image for the visual administration (faq.<indexterm><primary>faq</primary></indexterm>gif).</para></listitem></itemizedlist><para>The folder admin/case<indexterm><primary>admin/case</primary></indexterm> instead serves to define the module to be used in each specified case . This is important when, using the same admin file, we need to perform more operations using a CASE statement:<indexterm><primary>CASE statement</primary></indexterm></para><screen><![CDATA[case1 = insert
]]><![CDATA[case2 = cancel
]]><![CDATA[etc...
]]></screen><para>In fact it says which module to call in order to verify the CASE condition.<indexterm><primary>condition</primary></indexterm> For example, in the FAQ module there are lots of cases, here are the last 2:</para><screen><![CDATA[case "FaqAdmin":
]]><![CDATA[case "FaqCatGo":
]]><![CDATA[include ("admin/modules/adminfaq.php");
]]><![CDATA[break;
]]></screen><para>Both CASE statements call the adminfaq.<indexterm><primary>faq</primary></indexterm>php file, but they are used for different operations.<indexterm><primary>ations</primary></indexterm> The first one calls the file with the default scheme,<indexterm><primary>scheme</primary></indexterm> the second, on the other hand, gives its O:K. to insert a new category.<indexterm><primary>category</primary></indexterm> </para><para>This happens through a string like &ldquo;admin.php?<indexterm><primary>admin.php</primary></indexterm>op=FaqAdmin&rdquo; in the first case and &ldquo;admin.php?<indexterm><primary>admin.php</primary></indexterm>op=FaqCatGo&rdquo; in the second.</para><para>We will now create, in the following order, the files:</para><itemizedlist><listitem><para>admin/modules/topolino.<indexterm><primary>topolino</primary></indexterm>php</para></listitem><listitem><para>admin/case/case.topolino.<indexterm><primary>topolino</primary></indexterm>php</para></listitem><listitem><para>admin/links/links.topolino.<indexterm><primary>topolino</primary></indexterm>php </para></listitem></itemizedlist><para>In order to create the file inside the modules folder (modules/topolino.<indexterm><primary>topolino</primary></indexterm>php) we must have a structure of this type:</para><itemizedlist><listitem><para>Starting part of the file (Similar for all the modules)</para></listitem><listitem><para>Definition of the necessary functions.</para></listitem><listitem><para>Definition of the necessary cases in order to call the various functions for the admin module.<indexterm><primary>module</primary></indexterm></para></listitem><listitem><para>Final part of the file.</para></listitem></itemizedlist><para>The syntax for the starting part of the file is the following:</para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[if (!eregi("admin.php", $_SERVER['PHP_SELF'])) { die ("Access Denied"); }
]]><![CDATA[
]]><![CDATA[$querystr = "SELECT radminsuper, admlanguage FROM "
]]><![CDATA[.$prefix."_authors where aid='$aid'";
]]><![CDATA[$result = sql_query($querystr, $dbi) or die ("invalied query");
]]><![CDATA[
]]><![CDATA[list($radminsuper) = sql_fetch_row($result, $dbi);
]]><![CDATA[if ($radminsuper==1) {
]]></screen><para>This part of the file controls the administration rights for whoever calls it, a control on which language to use and (not in this module) a control<indexterm><primary>control</primary></indexterm> on the administrator's rights. An administrator could have only partial rights of administration on modules<indexterm><primary>modules</primary></indexterm> or some modules can be managed only by a superadmin.<indexterm><primary>superadmin</primary></indexterm> In our specific case the module can be managed only by the superadmin because the control is only:</para><screen><![CDATA[if ($radminsuper==1)
]]></screen><para>In case there are some specific rights (for example in the reviews module) the rights to control would have been:</para><screen><![CDATA[if (($radminreviews==1) OR ($radminsuper==1))
]]></screen><para>Activating the rights on two levels on new modules indeed isn't simple, you must specify in the nuke_authors table a new field that designates the rights, then modify admin/modules/authors.php adding the checkbox for the rights of the new module and modify the corresponding UPDATE queries.<indexterm><primary>queries</primary></indexterm></para><para>Let's go back to our module:<indexterm><primary>module</primary></indexterm> we have already seen the initial part, which is obligatorily. The end of the open IF statement is:</para><screen><![CDATA[} else {
]]><![CDATA[echo "Access Denied";
]]><![CDATA[}
]]></screen><para>All that we find in the middle, are the management functions and the cases that must be checked, which we will now go on to construct. There are a couple of rules to follow in order to construct the admin functions:</para><itemizedlist><listitem><para>We must include a header at the beginning of the function and a footer at the end:</para><screen><![CDATA[include("header.php");
]]><![CDATA[include("footer.php");
]]></screen></listitem></itemizedlist><para>We have to include the GraphicAdmin(); function immediately after the header.<indexterm><primary>header</primary></indexterm> It will display the navigation panel that leads to all the other admin<indexterm><primary>admin</primary></indexterm> links. The functions we'll now go to create are:</para><itemizedlist><listitem><para>Display of the database records</para></listitem><listitem><para>Selection of the record and its insertion in a modifiable text field</para></listitem><listitem><para>Modification of the record through insertion in the database of the value modified in the text field.</para></listitem></itemizedlist><para>Here is the code of the function which accomplishes the record selection:</para><screen><![CDATA[function mousedisplay() {
]]><![CDATA[ global $admin, $bgcolor2, $prefix, $dbi, $multilingual;
]]><![CDATA[ include ("header.php");
]]><![CDATA[ GraphicAdmin();
]]><![CDATA[ opentable();
]]><![CDATA[ $querystr = "SELECT idperson, nameperson FROM ".$prefix."_topolino";
]]><![CDATA[ $resultpersons = sql_query($querystr, $dbi)
]]><![CDATA[ or die ("invalid query in mousedisplay");
]]><![CDATA[ for ($m=0; $m < sql_num_rows($resultpersons, $dbi); $m++)
]]><![CDATA[ {
]]><![CDATA[ list ($idperson, $nameperson) = mysql_fetch_row($resultpersons);
]]><![CDATA[ $tmpLink = "<a href=\"admin.php?op=mouseselect&idtopo="
]]><![CDATA[ .$idperson."\">Select mouse</A><br>";
]]><![CDATA[ echo "$idperson - $nameperson $tmpLink";
]]><![CDATA[ }
]]><![CDATA[ closetable();
]]><![CDATA[ include("footer.php");
]]><![CDATA[}
]]></screen><para>The next function to implement is the one that corresponds to the selection of one of the three records:</para><screen><![CDATA[function mouseselect() {
]]><![CDATA[ global $admin, $bgcolor2, $prefix, $dbi, $multilingual, $idtopo;
]]><![CDATA[ include ("header.php");
]]><![CDATA[ GraphicAdmin();
]]><![CDATA[
]]><![CDATA[ opentable();
]]><![CDATA[ echo "idtopo=".$idtopo;
]]><![CDATA[ $querystr = "SELECT idperson, nameperson
]]><![CDATA[ FROM ".$prefix."_topolino where idperson='$idtopo'";
]]><![CDATA[ $resultpersons = sql_query($querystr, $dbi)
]]><![CDATA[ or die ("Invalid query in mouseselect");
]]><![CDATA[ for ($m=0; $m < sql_num_rows($resultpersons, $dbi); $m++){
]]><![CDATA[ list($idperson, $nameperson) = sql_fetch_row($resultpersons, $dbi);
]]><![CDATA[ echo "<form action=\"admin.php\" method=\"post\">";
]]><![CDATA[ echo "<input type=\"text\" name=\"nameperson\" size=\"20\"
]]><![CDATA[ maxlength=\"20\" value=\"$nameperson\"><br><br>";
]]><![CDATA[ echo "<input type=\"hidden\" name=\"idperson\"value=\"$idtopo\" > ";
]]><![CDATA[ echo "<input type=\"hidden\" name=\"op\" value=\"mousemodify\" > ";
]]><![CDATA[ echo "<input type=\"submit\" value=\""._ADDTOPO."\" > ";
]]><![CDATA[ echo "</form >";
]]><![CDATA[ }
]]><![CDATA[ closetable();
]]><![CDATA[
]]><![CDATA[ include("footer.php");
]]><![CDATA[}
]]></screen><para>It is very important to take note of some things:</para><orderedlist><listitem><para>The variables that we insert will be the ones to be checked, in fact you can see the variable &ldquo;$idtopo&rdquo; was inserted between the used variables. </para></listitem><listitem><para>The value checked in the CASE statements is passed to us through a hidden form field</para></listitem></orderedlist><screen><![CDATA[(< input type=\"hidden\"name=\"op\"value=\"mousemodify\">).
]]></screen><para>The last function we consider is the one that corresponds to the update<indexterm><primary>date</primary></indexterm> of the values in the database (Here too we added the two variables that we were interested in ($nameperson, $idperson): </para><screen><![CDATA[function mousemodify() {
]]><![CDATA[ global $admin, $bgcolor2, $prefix, $dbi, $multilingaul,
]]><![CDATA[$idtopo, $nameperson, $idperson;
]]><![CDATA[ include ("header.php");
]]><![CDATA[ GraphicAdmin();
]]><![CDATA[ Opentable();
]]><![CDATA[ sql_query("Update ".$prefix."_topolino set nameperson=' $nameperson'
]]><![CDATA[where idperson=$idperson", $dbi);
]]><![CDATA[ echo"OK";
]]><![CDATA[ die(mysql_error());
]]><![CDATA[ closetable();
]]><![CDATA[ include("footer.php");
]]><![CDATA[}
]]></screen><para>The last two elements to insert are the definitions for the CASE statements<indexterm><primary>statements</primary></indexterm> (that is, which function to call according to the variable passed to the module) and the closing of the file. </para><para>Definition of the cases:</para><screen><![CDATA[if ($radminsuper==1) {
]]><![CDATA[ switch($op) {
]]><![CDATA[ case "":
]]><![CDATA[ mousedisplay();
]]><![CDATA[ break;
]]><![CDATA[ case "topolino";
]]><![CDATA[ mousedisplay();
]]><![CDATA[ break;
]]><![CDATA[ case "mouseselect";
]]><![CDATA[ mouseselect();
]]><![CDATA[ break;
]]><![CDATA[ case "mousemodify";
]]><![CDATA[ mousemodify();
]]><![CDATA[ break;
]]><![CDATA[ }
]]><![CDATA[}
]]><![CDATA[else {
]]><![CDATA[ echo "Access Denied";
]]><![CDATA[}
]]></screen><para>The complete modules/topolino.<indexterm><primary>topolino</primary></indexterm>php file is thus (see also <ulink url="http://www.karakas-online.de/forum/viewtopic.php?p=367">Problems with new mods</ulink>):</para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[if (!eregi("admin.php", $_SERVER['PHP_SELF'])) { die ("Access Denied"); }
]]><![CDATA[
]]><![CDATA[$querystr = "SELECT radminsuper, admlanguage FROM "
]]><![CDATA[.$prefix."_authors where aid='$aid'";
]]><![CDATA[$result = sql_query($querystr, $dbi) or die ("invalied query");
]]><![CDATA[
]]><![CDATA[list($radminsuper) = sql_fetch_row($result, $dbi);
]]><![CDATA[if ($radminsuper==1) {
]]><![CDATA[ switch($op) {
]]><![CDATA[ case "":
]]><![CDATA[ mousedisplay();
]]><![CDATA[ break;
]]><![CDATA[ case "topolino";
]]><![CDATA[ mousedisplay();
]]><![CDATA[ break;
]]><![CDATA[ case "mouseselect";
]]><![CDATA[ mouseselect();
]]><![CDATA[ break;
]]><![CDATA[ case "mousemodify";
]]><![CDATA[ mousemodify();
]]><![CDATA[ break;
]]><![CDATA[ }
]]><![CDATA[}
]]><![CDATA[else {
]]><![CDATA[ echo "Access Denied";
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[function mousedisplay() {
]]><![CDATA[ global $admin, $bgcolor2, $prefix, $dbi, $multilingual;
]]><![CDATA[ include ("header.php");
]]><![CDATA[ GraphicAdmin();
]]><![CDATA[ Opentable();
]]><![CDATA[ $querystr = "SELECT idperson, nameperson FROM ".$prefix."_topolino";
]]><![CDATA[ $resultpersons = sql_query($querystr, $dbi)
]]><![CDATA[ or die ("invalid query in mousedisplay");
]]><![CDATA[ for ($m=0; $m < sql_num_rows($resultpersons, $dbi); $m++)
]]><![CDATA[ {
]]><![CDATA[ list ($idperson, $nameperson) = mysql_fetch_row($resultpersons);
]]><![CDATA[ $tmpLink = "<a href=\"admin.php?op=mouseselect&idtopo="
]]><![CDATA[ .$idperson."\">Select mouse</A><br>";
]]><![CDATA[ echo "$idperson - $nameperson $tmpLink";
]]><![CDATA[ }
]]><![CDATA[ closetable();
]]><![CDATA[ include("footer.php");
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[function mouseselect() {
]]><![CDATA[ global $admin, $bgcolor2, $prefix, $dbi, $multilingual, $idtopo;
]]><![CDATA[ include ("header.php");
]]><![CDATA[ GraphicAdmin();
]]><![CDATA[ Opentable();
]]><![CDATA[ echo "idtopo=".$idtopo;
]]><![CDATA[ $querystr = "SELECT idperson, nameperson FROM ".$prefix."_topolino
]]><![CDATA[ where idperson='$idtopo'";
]]><![CDATA[ $resultpersons = sql_query($querystr, $dbi)
]]><![CDATA[ or die ("Invalid query in mouseselect");
]]><![CDATA[ for ($m=0; $m < sql_num_rows($resultpersons, $dbi); $m++)
]]><![CDATA[ {
]]><![CDATA[ list($idperson, $nameperson) = sql_fetch_row($resultpersons, $dbi);
]]><![CDATA[ echo "<form action=\"admin.php\" method=\"post\">";
]]><![CDATA[ echo "<input type=\"text\" name=\"nameperson\" size=\"20\"
]]><![CDATA[ maxlength=\"20\" value=\"$nameperson\"><br><br>";
]]><![CDATA[ echo "<input type=\"hidden\" name=\"idperson\"value=\"$idtopo\" > ";
]]><![CDATA[ echo "<input type=\"hidden\" name=\"op\" value=\"mousemodify\" > ";
]]><![CDATA[ echo "<input type=\"submit\" value=\""._ADDTOPO."\" > ";
]]><![CDATA[ echo "</form >";
]]><![CDATA[ }
]]><![CDATA[ closetable();
]]><![CDATA[ include("footer.php");
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[function mousemodify() {
]]><![CDATA[ global $admin, $bgcolor2, $prefix, $dbi, $multilingaul, $idtopo,
]]><![CDATA[ $nameperson, $idperson;
]]><![CDATA[ include ("header.php");
]]><![CDATA[ GraphicAdmin();
]]><![CDATA[ Opentable();
]]><![CDATA[ sql_query("Update ".$prefix."_topolino set nameperson=' $nameperson'
]]><![CDATA[ where idperson=$idperson", $dbi);
]]><![CDATA[ echo"OK";
]]><![CDATA[ die(mysql_error());
]]><![CDATA[ closetable();
]]><![CDATA[ include("footer.php");
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[?>
]]><![CDATA[
]]></screen><para>The cases definition page is very easy to construct, it gathers the cases that are included in the file admin/modules/topolino.<indexterm><primary>topolino</primary></indexterm>php and puts them in the file admin/case/case.topolino.<indexterm><primary>topolino</primary></indexterm>php </para><para>This is the syntax:<indexterm><primary>syntax</primary></indexterm></para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[if (!eregi("admin.php", $_SERVER['PHP_SELF'])) { die ("Access Denied"); }
]]><![CDATA[switch($op) {
]]><![CDATA[ case "topolino":
]]><![CDATA[ include("admin/modules/topolino.php");
]]><![CDATA[ break;
]]><![CDATA[ case "mouseselect":
]]><![CDATA[ include("admin/modules/topolino.php");
]]><![CDATA[ break;
]]><![CDATA[ case "mousemodify":
]]><![CDATA[ include("admin/modules/topolino.php");
]]><![CDATA[ break;
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[>
]]></screen><para>The last two things we have to make are the compilation of the file admin/links/link.topolino.<indexterm><primary>topolino</primary></indexterm>php and the creation of a language module: Compilation of the file link.topolino.<indexterm><primary>topolino</primary></indexterm>php</para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[if ($radminsuper==1) {
]]><![CDATA[ adminmenu("admin.php?op=topolino ", "" _EDITTOPOLINO." ", "topolino.gif");
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[?>
]]></screen><para>Where: admin.php?op=topolino defines which module must be called, &quot; _EDITTOPOLINO<indexterm><primary>_EDITTOPOLINO</primary></indexterm>&quot; is the term to translate (it must be compiled in admin/language). For the modification of the language module I refer you to the previous paragraph with one single note. The language file of the admin section is common for all (admin/language), the relative languages must be added to the end of those that already exist. Just another thing, the syntax of this example is not perfect, its beyond the scope of this to make it work perfectly but it does illustrate the operation of the module (Which you will find available for download at <ulink url="http://www.spaghettibrain.com">www.spaghettibrain.com</ulink> so you will be able to study it).</para></sect1>
<sect1 id="include-HTML-file-in-module"><title>How to include a HTML file in a <application>PHP-Nuke</application> module</title><para>From what we have said about the structure of a <application>PHP-Nuke</application> module (see <xref linkend="module-structure">), it is easy to include a HTML file in a module - all we have to do is use the <acronym>PHP</acronym> include command,<indexterm><primary>command</primary></indexterm> to include it between the calls to OpenTable() and CloseTable() functions:</para><itemizedlist><listitem><para>Create a folder under the modules directory. Call it whatever you like, but take care to replace blanks with underscores<indexterm><primary>underscores</primary></indexterm> in the name.</para></listitem><listitem><para>Using a decent text editor (see <xref linkend="editing-PHP-Nuke-files">), create a text file called index.<indexterm><primary>index</primary></indexterm>php in that newly created directory.</para></listitem><listitem><para>Copy the following code in index.php:<indexterm><primary>index.php</primary></indexterm></para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[/************************************************************************/
]]><![CDATA[/* PHP-NUKE: Web Portal System */
]]><![CDATA[/* =========================== */
]]><![CDATA[/* */
]]><![CDATA[/* PHP-Nuke-HOWTO module for <application>PHP-Nuke</application> */
]]><![CDATA[/* */
]]><![CDATA[/* Copyright (c) 2003 index.php */
]]><![CDATA[/* by Chris Karakas */
]]><![CDATA[/* http://www.karakas-online.de */
]]><![CDATA[/* */
]]><![CDATA[/* See licence.html for the Licence of the other files */
]]><![CDATA[/* distributed together with this index.php file. */
]]><![CDATA[/* */
]]><![CDATA[/* This program is free software. You can redistribute it and/or modify */
]]><![CDATA[/* it under the terms of the <acronym>GNU</acronym> General Public License as published by */
]]><![CDATA[/* the Free Software Foundation; either version 2 of the License. */
]]><![CDATA[/************************************************************************/
]]><![CDATA[
]]><![CDATA[if (!eregi("modules.php", $PHP_SELF)) {
]]><![CDATA[ die ("You can't access this file directly...");
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[$index = 0; // 0 : do not show right blocks - 1:show right blocks
]]><![CDATA[require_once("mainfile.php");
]]><![CDATA[$module_name = basename(dirname(__FILE__));
]]><![CDATA[include("header.php");
]]><![CDATA[
]]><![CDATA[OpenTable();
]]><![CDATA[include("path/to/the/html/file"); // <-- CHANGE THIS!
]]><![CDATA[CloseTable();
]]><![CDATA[
]]><![CDATA[include("footer.php");
]]><![CDATA[
]]><![CDATA[?>
]]></screen></listitem><listitem><para>Change the licence to reflect your decisions. Of course, I urge you to use the <ulink url="http://www.gnu.org/copyleft/gpl.html">GNU General Public License</ulink> whenever possible, to help the cause of free software - <application>PHP-Nuke</application> is itself set under the GPL,<indexterm><primary>GPL</primary></indexterm> after all, so why would you want a different licence for your module?<indexterm><primary>module</primary></indexterm>. </para></listitem><listitem><para>Then just enter the right path to the HTML file you want to include, replacing the &ldquo;path/to/the/html/file&rdquo; string. This can be either a full filesystem path, or a relative one - relative to the <application>PHP-Nuke</application> root directory, which is always the same directory where config.<indexterm><primary>config</primary></indexterm>php is located. But it may also very well be a URL to a HTML file of another site. Examples:</para><screen><![CDATA[include("/usr/local/httpd/htdocs/myfile.html"); // absolute filesystem path
]]><![CDATA[include("modules/PHP-Nuke_HOWTO/cookies.html"); // relative filesstem path
]]><![CDATA[include("http://www.yoursite.com/filexx.html"); // full URL
]]></screen></listitem><listitem><para>Finally, activate the module from the modules administration (see <xref linkend="module-management">).</para></listitem></itemizedlist><tip>
<title>
Javascript in modules
</title>
<para>
There is nothing that prevents you from including a file that contains Javascript code in a module. As long as the Javascript functions defined in the included file are not also present in the includes/javascript.php file (see <xref linkend="javascript-php">), and the HTML page created with the Javascript does not break the table layout of your theme, there should be no problem. In this way you could create a <application>PHP-Nuke</application> Guestbook module, for example, if you already had the Javascript code for a guestbook (see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?p=58133">Javascript in themes</ulink>).
</para>
</tip>
<para>If you want to include two files in the module, so that they appear side-by-side, rather than one after the other, you can use the usual HTML table trick to show the files in two separate cells of the same table row (see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=19041">Using "include" for HTML pages</ulink>):</para><screen><![CDATA[OpenTable();
]]><![CDATA[echo "<table><tr><td>";
]]><![CDATA[include ("page.html");
]]><![CDATA[echo "</td><td>";
]]><![CDATA[include ("page2.html");
]]><![CDATA[echo "</td></tr></table";
]]><![CDATA[CloseTable();
]]></screen><para>An alternative way to include a HTML file in the module,<indexterm><primary>module</primary></indexterm> is to terminate <acronym>PHP</acronym> interpretation of the file with a closing ?&gt;, include the HTML code verbatim and then reopen the <acronym>PHP</acronym> context with a new &lt;?php line:</para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[if (!eregi("modules.php", $PHP_SELF)) {
]]><![CDATA[die ("You can't access this file directly...");
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[$index = 0; // 0 : do not show right blocks - 1:show right blocks
]]><![CDATA[require_once("mainfile.php");
]]><![CDATA[$module_name = basename(dirname(__FILE__));
]]><![CDATA[include("header.php");
]]><![CDATA[
]]><![CDATA[OpenTable();
]]><![CDATA[?>
]]><![CDATA[
]]><![CDATA[PUT YOUR HTML CODE HERE, WHATEVER COMES BETWEEN THE <html> AND </html>
]]><![CDATA[TAGS OF YOUR HTML FILE
]]><![CDATA[
]]><![CDATA[<?php
]]><![CDATA[CloseTable();
]]><![CDATA[
]]><![CDATA[include("footer.php");
]]><![CDATA[?>
]]></screen><para>Note that we have inserted a closing ?&gt; after the call to OpenTable() and an opening &lt;?php before the call to CloseTable(). Whatever comes in between, should be plain HTML code, not <acronym>PHP</acronym>.<indexterm><primary>PHP</primary></indexterm> This method is suitable for small HTML texts, for larger texts the include method is recommended.</para></sect1>
<sect1 id="include-HTML-file-and-links-in-module"><title>How to include a HTML file and its links in a <application>PHP-Nuke</application> module</title><para>If the HTML file you included in your module with the methods shown in <xref linkend="include-HTML-file-in-module"> contains links to HTML files that you would also like to have included, you will need to apply some additional handwork. The problem here is that, although the included file will show correctly inside your module (and your theme), as soon as you click on one of its HTML links, you will be shown the target HTML file as is, i.e. outside your <application>PHP-Nuke</application> environment, like any other file independent of <application>PHP-Nuke</application>. This is certainly not something you are going to like - otherwise, why go into the trouble of including the first HTML file anyway? It is clear that, for a collection of interlinked HTML documents, a better approach is needed.</para><tip>
<title>
See the <application>PHP-Nuke</application> HOWTO module!
</title>
<para>
For a real world example of including a large collection of HTML documents in a <application>PHP-Nuke</application> module, download and install the <ulink url="http://www.karakas-online.de/EN-Book/EN-Book-Nuke.tar.gz">PHP-Nuke HOWTO module</ulink>. Then, see how modules/PHP-Nuke_HOWTO/index.php is programmed, as well as how the HTML links to files of the HOWTO were set up.
</para>
</tip>
<para>In the method we will present here, we use an URL parameter (&ldquo;page&rdquo;) to find out which file to include in index.php.<indexterm><primary>index.php</primary></indexterm> Every link to a file of our collection is changed to contain this URL parameter.<indexterm><primary>parameter</primary></indexterm> The page URL parameter is validated through an associative array, minimizing the risk for SQL injection and other cracking attacks (see <xref linkend="SQL-injection-with-php-nuke">). For a simpler, but not universal, method using iframes,<indexterm><primary>frames</primary></indexterm> see <xref linkend="include-HTML-file-and-links-in-module-iframe">.</para><para>Proceed in two steps as follows:</para><orderedlist><listitem><para>Change every HTML link that appears in your HTML documents and points to another document of the same collection (links to other documents should be left unchanged) For example, a link to somefile.html like the following one</para><screen><![CDATA[<a href="somefile.html">
]]></screen><para>should be changed to </para><screen><![CDATA[<a href="modules.php?name=Your_Module&amp;page=somefile.html">
]]></screen><para>where you should replace &quot;Your_Module&quot;<indexterm><primary>Your_Module</primary></indexterm> with the name of your module, of course. This link passes the filename as the value of the page URL parameter to Your_Module.<indexterm><primary>Your_Module</primary></indexterm> You should do this for every link in your HTML document collection that points to another file of the same collection.</para></listitem><listitem><para>As a next step, you modify the index.<indexterm><primary>index</primary></indexterm>php file of your <application>PHP-Nuke</application> module slightly (this is the file modules/Your_Module/index.php,<indexterm><primary>index.php</primary></indexterm> if we stay with the module naming of our example). You add a line for every file that was involved in a link modification above. This means that for every file like somefile.html in the above example, you add a line</para><screen><![CDATA[$ACCEPT_FILE['somefile.html'] = 'somefile.html';
]]></screen></listitem></orderedlist><para>Thus, if your HTML file collection consists of the files</para><screen><![CDATA[accelerating-php-nuke.html
]]><![CDATA[add-on-blocks.html
]]><![CDATA[add-on-modules.html
]]><![CDATA[administration-functions.html
]]><![CDATA[admin-management.html
]]></screen><para>then, following the above step 1, you should change every HTML link in those files as shown in <xref linkend="tab-changing-HTML-links">.</para><para><table id="tab-changing-HTML-links"><title>Changing HTML links for use in a custom <application>PHP-Nuke</application> module</title><tgroup cols="2" colsep="1" rowsep="1">
<colspec colname="col0" align="left">
<colspec colname="col1" align="left">
<tbody>
<row>
<entry align="left" valign="top"><para>Original link</para></entry>
<entry align="left" valign="top"><para>Changed link</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&lt;a href=&quot;accelerating-php-nuke.html&quot;&gt;</para></entry>
<entry align="left" valign="top"><para>&lt;a href=&quot;modules.php?name=Your_Module</para><para>&amp;amp;page=accelerating-php-nuke.html&quot;&gt;</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&lt;a href=&quot;add-on-blocks.html&quot;&gt;</para></entry>
<entry align="left" valign="top"><para>&lt;a href=&quot;modules.php?name=Your_Module</para><para>&amp;amp;page=add-on-blocks.html&quot;&gt;</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&lt;a href=&quot;add-on-modules.html&quot;&gt;</para></entry>
<entry align="left" valign="top"><para>&lt;a href=&quot;modules.php?name=Your_Module</para><para>&amp;amp;page=add-on-modules.html&quot;&gt;</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&lt;a href=&quot;administration-functions.html&quot;&gt;</para></entry>
<entry align="left" valign="top"><para>&lt;a href=&quot;modules.php?name=Your_Module</para><para>&amp;amp;page=administration-functions.html&quot;&gt;</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&lt;a href=&quot;admin-management.html&quot;&gt;</para></entry>
<entry align="left" valign="top"><para>&lt;a href=&quot;modules.php?name=Your_Module</para><para>&amp;amp;page=admin-management.html&quot;&gt;</para></entry>
</row>
</tbody>
</tgroup></table></para><para>After that, following step 2 above, you should insert the following lines in the index.php file of Your_Module:<indexterm><primary>Your_Module</primary></indexterm></para><screen><![CDATA[$ACCEPT_FILE['accelerating-php-nuke.html'] = 'accelerating-php-nuke.html';
]]><![CDATA[$ACCEPT_FILE['add-on-blocks.html'] = 'add-on-blocks.html';
]]><![CDATA[$ACCEPT_FILE['add-on-modules.html'] = 'add-on-modules.html';
]]><![CDATA[$ACCEPT_FILE['administration-functions.html'] = 'administration-functions.html';
]]><![CDATA[$ACCEPT_FILE['admin-management.html'] = 'admin-management.html';
]]></screen><para>The ACCEPT_FILE plays the role of a validator for the page URL parameter.<indexterm><primary>parameter</primary></indexterm> It connects a value of &ldquo;page&rdquo;, as passed by some URL,<indexterm><primary>URL</primary></indexterm> with the name of a file that has to be selected. The way we programmed it above, ACCEPT_FILE points to the file accelerating-php-nuke.html when given the &ldquo;page&rdquo; argument 'accelerating-php-nuke.html' (i.e. when &ldquo;page&rdquo; was 'accelerating-php-nuke.html' on the URL). This may look trivial,<indexterm><primary>trivial</primary></indexterm> but is not. What's more, there is nothing that would prevent you from choosing a different (and less intuitive) mapping from the values of &ldquo;page&rdquo; to the selected filenames. </para><para>Thus, you could decide that a &ldquo;page&rdquo; (URL parameter) value of &ldquo;1&rdquo; means the accelerating-php-nuke.html file, a vlaue of &ldquo;2&rdquo; the add-on-blocks.html file etc. Then, the ACCEPT_FILE assignments would look as follows:</para><screen><![CDATA[$ACCEPT_FILE['1'] = 'accelerating-php-nuke.html';
]]><![CDATA[$ACCEPT_FILE['2'] = 'add-on-blocks.html';
]]><![CDATA[$ACCEPT_FILE['3'] = 'add-on-modules.html';
]]><![CDATA[$ACCEPT_FILE['4'] = 'administration-functions.html';
]]><![CDATA[$ACCEPT_FILE['5'] = 'admin-management.html';
]]></screen><para>while the HTML links in the files themselves should be changed as indicated by <xref linkend="tab-changing-HTML-links-2">.</para><para><table id="tab-changing-HTML-links-2"><title>Alternative way of changing HTML links for use in a custom <application>PHP-Nuke</application> module</title><tgroup cols="2" colsep="1" rowsep="1">
<colspec colname="col0" align="left">
<colspec colname="col1" align="left">
<tbody>
<row>
<entry align="left" valign="top"><para>Original link</para></entry>
<entry align="left" valign="top"><para>Changed link</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&lt;a href=&quot;accelerating-php-nuke.html&quot;&gt;</para></entry>
<entry align="left" valign="top"><para>&lt;a href=&quot;modules.php?name=Your_Module</para><para>&amp;amp;page=1&quot;&gt;</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&lt;a href=&quot;add-on-blocks.html&quot;&gt;</para></entry>
<entry align="left" valign="top"><para>&lt;a href=&quot;modules.php?name=Your_Module</para><para>&amp;amp;page=2&quot;&gt;</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&lt;a href=&quot;add-on-modules.html&quot;&gt;</para></entry>
<entry align="left" valign="top"><para>&lt;a href=&quot;modules.php?name=Your_Module</para><para>&amp;amp;page=3&quot;&gt;</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&lt;a href=&quot;administration-functions.html&quot;&gt;</para></entry>
<entry align="left" valign="top"><para>&lt;a href=&quot;modules.php?name=Your_Module</para><para>&amp;amp;page=4&quot;&gt;</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&lt;a href=&quot;admin-management.html&quot;&gt;</para></entry>
<entry align="left" valign="top"><para>&lt;a href=&quot;modules.php?name=Your_Module</para><para>&amp;amp;page=5&quot;&gt;</para></entry>
</row>
</tbody>
</tgroup></table></para><para>The idea is that you retain control of what filename is selected. If you would blindly set the name of the selected file to be equal to the passed parameter value of &ldquo;page&rdquo;, then a malicious user could use the URL<indexterm><primary>URL</primary></indexterm></para><screen><![CDATA[modules.php?name=Your_Module&amp;page=/etc/passwd
]]></screen><para>and read the contents of the system's password file (or whatever other file readable by the web server,<indexterm><primary>server</primary></indexterm> for that matter). The use of an associative mapping between URL parameters and filenames, as the one implemented by the ACCEPT_FILE array above, is thus not a gimmic, but a necessity. It protects your module from SQL injections and other attacks that rely on the programmer being too lazy to verify user input. See <xref linkend="security"> for more on <application>PHP-Nuke</application> security in general and <xref linkend="SQL-injection-with-php-nuke"> for SQL injections with <application>PHP-Nuke</application> in particular.</para><para>However, even with these precautions in place, the module is still vulnerable to a serious attack, as <ulink url="http://www.waraxe.us">waraxe</ulink> has pointed out in a security advisory (to be published): if the $ACCEPT_FILE array is not initialized, one could &ldquo;poison&rdquo; it. This means that an attacker could pass the parameters '...&amp;page=xxx&amp;ACCEPT_FILE[xxx]=/etc/passwd' on the URL and could still get /etc/passwd (or any other file for that matter) back! This will not work if safe_mode is ON in php.ini, but it still poses a very serious threat. For this reason, we must initialize the array first:</para><screen><![CDATA[// We initialize the array, to avoid attacks based on poisoning the
]]><![CDATA[// <acronym>PHP</acronym> global variable space. Thanks to waraxe for pointing this out!
]]><![CDATA[// See http://www.waraxe.us
]]><![CDATA[//
]]><![CDATA[$ACCEPT_FILE = array();
]]></screen><para>Now you can hopefully see how important is the following rule:</para><important>
<title>
Don't forget:
</title>
<para>
Always initialize your variables!
</para>
</important>
<para>The complete code of modules/Your_Module/index.<indexterm><primary>index</primary></indexterm>php is thus:</para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[/************************************************************************/
]]><![CDATA[/* PHP-NUKE: Web Portal System */
]]><![CDATA[/* =========================== */
]]><![CDATA[/* */
]]><![CDATA[/* PHP-Nuke-HOWTO module for <application>PHP-Nuke</application> */
]]><![CDATA[/* */
]]><![CDATA[/* Copyright (c) 2003 index.php */
]]><![CDATA[/* by Chris Karakas */
]]><![CDATA[/* http://www.karakas-online.de */
]]><![CDATA[/* */
]]><![CDATA[/* See licence.html for the Licence of the other files */
]]><![CDATA[/* distributed together with this index.php file. */
]]><![CDATA[/* */
]]><![CDATA[/* This program is free software. You can redistribute it and/or modify */
]]><![CDATA[/* it under the terms of the <acronym>GNU</acronym> General Public License as published by */
]]><![CDATA[/* the Free Software Foundation; either version 2 of the License. */
]]><![CDATA[/************************************************************************/
]]><![CDATA[
]]><![CDATA[if (!eregi("modules.php", $PHP_SELF)) {
]]><![CDATA[ die ("You can't access this file directly...");
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[$index = 0; // 0 : do not show right blocks - 1:show right blocks
]]><![CDATA[require_once("mainfile.php");
]]><![CDATA[$module_name = basename(dirname(__FILE__));
]]><![CDATA[include("header.php");
]]><![CDATA[
]]><![CDATA[// We initialize the array, to avoid attacks based on poisoning the
]]><![CDATA[// <acronym>PHP</acronym> global variable space. Thanks to waraxe for pointing this out!
]]><![CDATA[// See http://www.waraxe.us
]]><![CDATA[//
]]><![CDATA[$ACCEPT_FILE = array();
]]><![CDATA[
]]><![CDATA[$ACCEPT_FILE['accelerating-php-nuke.html'] = 'accelerating-php-nuke.html';
]]><![CDATA[$ACCEPT_FILE['add-on-blocks.html'] = 'add-on-blocks.html';
]]><![CDATA[$ACCEPT_FILE['add-on-modules.html'] = 'add-on-modules.html';
]]><![CDATA[$ACCEPT_FILE['administration-functions.html'] = 'administration-functions.html';
]]><![CDATA[$ACCEPT_FILE['admin-management.html'] = 'admin-management.html';
]]><![CDATA[
]]><![CDATA[OpenTable();
]]><![CDATA[$php_ver = phpversion();
]]><![CDATA[$php_ver = explode(".", $php_ver);
]]><![CDATA[$phpver = "$php_ver[0]$php_ver[1]";
]]><![CDATA[if ($phpver >= 41) {
]]><![CDATA[ $page = $_GET['page'];
]]><![CDATA[} else {
]]><![CDATA[ $page = $HTTP_GET_VARS['page'];
]]><![CDATA[}
]]><![CDATA[$pagename = $ACCEPT_FILE[$page];
]]><![CDATA[if (!isSet($pagename)) $pagename = "accelerating-php-nuke.html"; // default file
]]><![CDATA[include("modules/Your_Module/$pagename");
]]><![CDATA[CloseTable();
]]><![CDATA[
]]><![CDATA[include("footer.php");
]]><![CDATA[
]]><![CDATA[?>
]]></screen><para>As you can easily deduce from the above code, the &quot;page&quot; URL parameter is firtst extracted using either the <ulink url="http://www.php.net/manual/en/reserved.variables.php#reserved.variables.get">GET superglobal</ulink>, if the <acronym>PHP</acronym> version is at least 4.1, or the $HTTP_GET_VARS array otherwise. The associated filename is then computed from the ACCEPT_FILE array. If the user (maliciously or not) entered a value for &ldquo;page&rdquo; that could not be mapped to a filename,<indexterm><primary>filename</primary></indexterm> a default file is used (the accelerating-php-nuke.html in the example). Finally, the computed filename is included, just as we have seen in the simpler examples of <xref linkend="include-HTML-file-in-module">.</para><tip>
<title>
Automate!
</title>
<para>
Most of the work in the method we presented, will revolve around changing links in the various files and adding the right ACCEPT_FILE line for each file in index.php. This is an error prone procedure, even with just a few files. You should thus automate it with whatever tools you have at your disposal. For the creation of the <ulink url="http://www.karakas-online.de/EN-Book/EN-Book-Nuke.tar.gz">PHP-Nuke HOWTO module</ulink>, for example, a shell script is used to produce dynamically the right sed commands, which are then executed to produce the link substitutions. The ACCEPT_FILE lines are also produced automatically. The result is a perfectly integrated <application>PHP-Nuke</application> module, even with the hundreds of files that comprise this HOWTO. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_smile.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_smile.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_smile.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_smile.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject>
</para>
</tip>
</sect1>
<sect1 id="include-HTML-file-and-links-in-module-iframe"><title>How to include a HTML file and its links using an iframe in a <application>PHP-Nuke</application> module</title><para>You can also use an iframe to include an external HTML page in your module.<indexterm><primary>module</primary></indexterm> An inline frame (iframe) is a construct which embeds a document into an HTML document so that embedded data is displayed inside a subwindow of the browser's window. This does not mean full inclusion; the two documents are independent, and both them are treated as complete documents, instead of treating one as part of the other (see <ulink url="http://www.cs.tut.fi/~jkorpela/html/iframe.html">Using inline frames (iframe elements) to embed documents into HTML documents</ulink>).</para><para>Iframes are not supported by all browsers, however they offer a much more comfortable alternative to the solution of <xref linkend="include-HTML-file-and-links-in-module">, since any links of the included HTML page will be shown in the iframe,<indexterm><primary>frame</primary></indexterm> if they are linked with a relative URL.<indexterm><primary>URL</primary></indexterm> To include a HTML file and its links in a <application>PHP-Nuke</application> module,<indexterm><primary>module</primary></indexterm> use the following as the index.<indexterm><primary>index</primary></indexterm>php file of the module (see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?p=58549">Adding Links To The Main Page (Modules)</ulink> and <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=388">Make <application>PHP-Nuke</application> Use "Frame Like target"</ulink>):</para><screen><![CDATA[<?
]]><![CDATA[
]]><![CDATA[if (!eregi("modules.php", $_SERVER['PHP_SELF'])) {
]]><![CDATA[ die ("You can't access this file directly...");
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[if(!IsSet($mainfile)) { include ("mainfile.php"); }
]]><![CDATA[$index=0;
]]><![CDATA[
]]><![CDATA[$theme="DeepBlue";
]]><![CDATA[$go_to_address1="http://www.karakas-online.de/EN-Book/book1.html";
]]><![CDATA[
]]><![CDATA[$go_to_address=rawurldecode($go_to_address1);
]]><![CDATA[include("header.php");
]]><![CDATA[
]]><![CDATA[OpenTable();
]]><![CDATA[echo "<center><h4><a href=\"index.php\">Click to close.</a></h4></center>";
]]><![CDATA[echo "<iframe SRC=\"".$go_to_address."\" width=\"100%\" height=\"1200\"
]]><![CDATA[framespacing=0 frameborder=no border=0 scrolling=auto></iframe>";
]]><![CDATA[echo "<br><center>NB. Using iframes!</center><br>";
]]><![CDATA[CloseTable();
]]><![CDATA[
]]><![CDATA[include("footer.php");
]]><![CDATA[die;
]]><![CDATA[
]]><![CDATA[?>
]]><![CDATA[
]]></screen><para>You only have to enter the HTTP address of the page to be included in $go_to_address1 and the desired theme in $theme (or, if you want to use whatever theme<indexterm><primary>theme</primary></indexterm> is currently used, comment the $theme line). Activate the module and you are done (<xref linkend="fig-iframes">)!</para><para>
<figure id="fig-iframes">
<title>
<application>PHP-Nuke</application> HOWTO included in a module with the help of an iframe.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1172;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1172;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1172;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1172;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>PHP-Nuke HOWTO included in a module with the help of an iframe.</phrase>
</textobject>
<caption>
<para>PHP-Nuke HOWTO included in a module with the help of an iframe.</para>
</caption>
</mediaobject>
</figure>
</para><tip>
<title>
Include the <application>PHP-Nuke</application> HOWTO as a module in your <application>PHP-Nuke</application> site!
</title>
<para>
You can include the <ulink url="http://www.karakas-online.de/EN-Book/">PHP-Nuke HOWTO</ulink> in your <application>PHP-Nuke</application> site as a module using either the method of <xref linkend="include-HTML-file-and-links-in-module"> or the method of <xref linkend="include-HTML-file-and-links-in-module-iframe">!
</para>
<para>
To use the method of <xref linkend="include-HTML-file-and-links-in-module">, download the <ulink url="http://www.karakas-online.de/EN-Book/EN-Book-Nuke.tar.gz">PHP-Nuke module version of the <application>PHP-Nuke</application> HOWTO</ulink> and install it according to the instruction in the accompanying INSTALL file.
</para>
<para>
To use the method of <xref linkend="include-HTML-file-and-links-in-module-iframe">, just make a module with an index.php file exactly as in the example shown there. It will show the starting page of the PHP-HOWTO in an iframe (<xref linkend="fig-iframes">) and you will be able to navigate its pages without installing anything locally. You have Chris' explicit permission for this.
<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_smile.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_smile.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_smile.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_smile.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject>
</para>
</tip>
<para>Besides browser compatibility issues, the iframe method has also problems when it comes to printing.<indexterm><primary>printing</primary></indexterm> For more information on iframes,<indexterm><primary>frames</primary></indexterm> see <ulink url="http://www.cs.tut.fi/~jkorpela/html/iframe.html">Using inline frames (iframe elements) to embed documents into HTML documents</ulink>.</para></sect1>
<sect1 id="include-plain-text-file-in-module"><title>How to include a plain text file in a <application>PHP-Nuke</application> module</title><para>A plain text file needs a somewhat different treatment than a HTML file, if it is to be included in a <application>PHP-Nuke</application> module.<indexterm><primary>module</primary></indexterm> The reason is that a plain text file lacks the formatting tags that are present in a usual HTML file. If you simply include it as shown in <xref linkend="include-HTML-file-in-module">, it will show as a single paragraph, lacking any structure.<indexterm><primary>structure</primary></indexterm> </para><para>Why? Because the &ldquo;formatting tags&rdquo; of a plain text file are the newline characters. They will introduce a new line - and a new paragraph. In HTML however, a newline will not suffice, you need a break tag (&lt;br&gt;) to achieve the same effect. Since a <application>PHP-Nuke</application> module is a <acronym>PHP</acronym> file, and as such it will be transformed to a HTML file for the visitor,<indexterm><primary>visitor</primary></indexterm> we need to play by the HTML rules if we want our file to be formatted correctly.</para><para>Fortunately, the <ulink url="http://www.php.net/manual/en/function.nl2br.php">nl2br <acronym>PHP</acronym> function</ulink> (newline to break) comes to our rescue here: it will automatically insert<indexterm><primary>insert</primary></indexterm> HTML &lt;br /&gt; tags (breaks) before every newline in the text file. Replace </para><screen><![CDATA[OpenTable();
]]><![CDATA[include("path/to/the/html/file"); // <-- CHANGE THIS!
]]><![CDATA[CloseTable();
]]></screen><para>in the code of <xref linkend="include-HTML-file-in-module"> with (see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=12926">another adding module question</ulink>):</para><screen><![CDATA[OpenTable();
]]><![CDATA[$filename = "path/to/the/text/file"; // <-- CHANGE THIS!
]]><![CDATA[$content_array = file($filename);
]]><![CDATA[$content = implode("", $content_array);
]]><![CDATA[print nl2br($content);
]]><![CDATA[CloseTable();
]]></screen></sect1>
<sect1 id="javascript-in-php-nuke-modules"><title>How to use Javascript in <application>PHP-Nuke</application> modules</title><para>You can include Javascript code in modules without problems in <application>PHP-Nuke</application>. You can proceed in two ways:</para><itemizedlist><listitem><para>Include your Javascript functions in javascript.<indexterm><primary>javascript</primary></indexterm>php (<xref linkend="javascript-php">).</para></listitem><listitem><para>Include your complete Javascript code in the module (<xref linkend="javascript-in-php-nuke-modules-complete">)</para></listitem></itemizedlist><sect2 id="javascript-php"><title>Javascript functions in javascript.php</title><para>PHP-Nuke come with its own Javascript functions included in the file javascript.<indexterm><primary>javascript</primary></indexterm>php, located under the includes folder. You can add your own Javascript code there, if you follow some simple rules:<indexterm><primary>rules</primary></indexterm></para><itemizedlist><listitem><para>Use a decent text editor (see <xref linkend="editing-PHP-Nuke-files">) to edit the file.</para></listitem><listitem><para>Append your code after the code already there, but before the ending ?&gt; line.</para></listitem><listitem><para>&ldquo;echo&rdquo; each line of your Javascript script. Example: Instead of entering directly the script code:</para><screen><![CDATA[<script type="text/javascript">
]]><![CDATA[<!--
]]><![CDATA[function openwindow(){
]]><![CDATA[ window.open
]]><![CDATA[("modules/$name/copyright.php","Copyright","toolbar=no,location=no,directories=no,
]]><![CDATA[status=no,scrollbars=yes,resizable=no,copyhistory=no,width=400,height=200")
]]><![CDATA[}
]]><![CDATA[//-->
]]><![CDATA[</script>
]]></screen></listitem><listitem><para>enter it with &ldquo;echo&rdquo;s as:</para><screen><![CDATA[echo "<script type=\"text/javascript\">\n";
]]><![CDATA[echo "<!--\n";
]]><![CDATA[echo "function openwindow(){\n";
]]><![CDATA[echo " window.open(\"modules/$name/copyright.php\",\"Copyright\",
]]><![CDATA[\"toolbar=no,location=no,directories=no,status=no,
]]><![CDATA[scrollbars=yes,resizable=no,copyhistory=no,width=400,height=200\");\n";
]]><![CDATA[echo "}\n";
]]><![CDATA[echo "//-->\n";
]]><![CDATA[echo "</script>\n\n";
]]></screen></listitem><listitem><para>Enclose each line in double quotes,<indexterm><primary>quotes</primary></indexterm> like a string, and escape (with a backslash \) any double quote inside that string.</para></listitem><listitem><para>Add a newline character (\n) to the string, before the closing double quote<indexterm><primary>quote</primary></indexterm><footnote><para>the &ldquo;window.open<indexterm><primary>window.open</primary></indexterm>&rdquo; line in the example above is actually a long line that has been broken to 3 lines only for layout purposes, that's why there are no newlines (\n) at the ends of two lines (just as there is no semicolon for the same reason).</para></footnote>.</para></listitem><listitem><para>End each line, like every <acronym>PHP</acronym> line, with a semicolon (;).</para></listitem></itemizedlist><para>If you use vi (see <xref linkend="vi">), the following sequence of vi commands, applied to a Javascript file, will produce the right <acronym>PHP</acronym> code to append in the javascript.<indexterm><primary>javascript</primary></indexterm>php file:</para><screen>
1,$s/"/\\"/g <co id="vi1">
1,$s/^/echo "/ <co id="vi2">
1,$s/$/";/ <co id="vi3">
1,$s/";$/\\n";/ <co id="vi4">
</screen>
<calloutlist>
<callout arearefs="vi1">
<para>
Escape all double quotes.
</para>
</callout>
<callout arearefs="vi2">
<para>
Add 'echo "' at the start of every line.
</para>
</callout>
<callout arearefs="vi3">
<para>
Add '";' at the end of every line.
</para>
</callout>
<callout arearefs="vi4">
<para>
Add a newline '\n' at the end of each Javascript line.
</para>
</callout>
</calloutlist>
<para>You can then include calls to your Javascript functions in the HTML code of your module.<indexterm><primary>module</primary></indexterm> You echo the Javascript code, just like any other HTML code.</para></sect2>
<sect2 id="javascript-in-php-nuke-modules-complete"><title>Complete Javascript code in modules</title><para>You can use the following template to include your complete Javascript code in your <application>PHP-Nuke</application> module:<indexterm><primary>module</primary></indexterm></para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[if (!eregi("modules.php", $PHP_SELF)) {
]]><![CDATA[ die ("You can't access this file directly...");
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[require_once("mainfile.php");
]]><![CDATA[
]]><![CDATA[// 0 : do not show right blocks - 1:show right blocks
]]><![CDATA[$index = 0;
]]><![CDATA[
]]><![CDATA[include("header.php");
]]><![CDATA[?>
]]><![CDATA[
]]><![CDATA[// PUT HTML OR JAVASCRIPT CODE HERE,
]]><![CDATA[// OR GET RID OF THE ?> AND <?php ABOVE AND BELOW THIS LINE
]]><![CDATA[// AND USE <acronym>PHP</acronym> CODE HERE INSTEAD.
]]><![CDATA[
]]><![CDATA[<?php
]]><![CDATA[include("footer.php");
]]><![CDATA[?>
]]></screen><tip>
<title>
Javascript with PHP
</title>
<para>
If you decide to use <acronym>PHP</acronym> code ("echo"s) to enter your Javascript code, you should take into account the rules presented in <xref linkend="javascript-php">.
</para>
</tip>
<tip>
<title>
Javascript codebase
</title>
<para>
You may need to add the following line to your Javascript applet:
</para>
<screen><![CDATA[codebase="modules/modulename"]]></screen>
</tip>
</sect2>
</sect1>
<sect1 id="create-logout-module"><title>How to create a Logout module</title><para>
<figure id="fig-logout-module">
<title>
Logout link in the Modules block.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1173;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1173;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1173;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1173;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Logout link in the Modules block.</phrase>
</textobject>
<caption>
<para>Logout link in the Modules block.</para>
</caption>
</mediaobject>
</figure>
</para><para>Do you consider it too much work for your registered users to have to click<indexterm><primary>click</primary></indexterm> on the &ldquo;Your Account<indexterm><primary>Your Account</primary></indexterm>&rdquo; link in the Modules block,<indexterm><primary>block</primary></indexterm> be directed to their personal account page, then have to click on &ldquo;Logout<indexterm><primary>Logout</primary></indexterm>&rdquo; in order to get logged out of your site? Why not have a direct &ldquo;Logout<indexterm><primary>Logout</primary></indexterm>&rdquo; link in the Modules block?<indexterm><primary>block</primary></indexterm> Well, since all links in the Modules block are automatically created from the active modules (unless you created a custom<indexterm><primary>custom</primary></indexterm> Modules block along the lines of <xref linkend="build-custom-module-blocks">), asking for a Logout link in the Modules block is asking for a Logout<indexterm><primary>Logout</primary></indexterm> module!</para><para>In fact, it is easy to construct a Logout module - and is another example of using Javascript in modules (see <xref linkend="javascript-in-php-nuke-modules">):</para><para>Create a new folder, call it Logout,<indexterm><primary>Logout</primary></indexterm> in the modules directory. In the Logout folder, create an index.<indexterm><primary>index</primary></indexterm>php file that contains (see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=18297">Add "Logout" to Modules Block</ulink>):</para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[echo "
]]><![CDATA[<script type=\"text/javascript\">
]]><![CDATA[top.location.replace ('modules.php?name=Your_Account&file=index&op=logout')
]]><![CDATA[</script>
]]><![CDATA["
]]><![CDATA[
]]><![CDATA[?>
]]></screen><para>Activate the Logout module from the administration panel.<indexterm><primary>panel</primary></indexterm> From now on, a Logout link will appear in the Modules block - it will log a registered user immediately upon clicking on it.</para></sect1>
<sect1 id="advertisements-in-php-nuke-modules"><title>How to show advertisements in <application>PHP-Nuke</application> modules</title><para>So now you have seen how nice your new AdSense block (<xref linkend="advertisements-in-php-nuke-blocks">) looks and you've got appetite for more? Here you are:</para><itemizedlist><listitem><para>Google AdSense in the News module (<xref linkend="Google-AdSense-in-news-module">),</para></listitem><listitem><para>Google AdSense on top of a <application>PHP-Nuke</application> module (<xref linkend="Google-AdSense-on-top-of-php-nuke-module">).</para></listitem></itemizedlist><sect2 id="Google-AdSense-in-news-module"><title>Google AdSense in the News module</title><para>Wouldn't it be nice to have your Google AdSense placed just right to a news<indexterm><primary>news</primary></indexterm> article?<indexterm><primary>article</primary></indexterm> The solution we will present here, taken from <ulink url="http://www.luchtzak.be/modules.php?name=Google_AdSense_PHP-Nuke">Google AdSense in PHP-Nuke</ulink>, can be used as a starting point for introducing AdSense (and other similar advertisement schemes) in modules other than the News module.<indexterm><primary>module</primary></indexterm> </para><para>In file modules/News/article.<indexterm><primary>article</primary></indexterm>php, look for the following code:</para><screen><![CDATA[$boxtitle = ""._RELATED."";
]]><![CDATA[$boxstuff = "<font class=\"content\">";
]]><![CDATA[$sql = "select name, url from ".$prefix."_related where tid=$topic";
]]><![CDATA[$result = $db->sql_query($sql);
]]><![CDATA[while ($row = $db->sql_fetchrow($result)) {
]]><![CDATA[$name = $row[name];
]]><![CDATA[$url = $row[url];
]]><![CDATA[$boxstuff .= "<strong><big>&middot;</big></strong>&nbsp;<a href=\"$url\"
]]><![CDATA[target=\"new\">$name</a><br>\n";
]]><![CDATA[}
]]></screen><para>just before that, add the following:</para><screen><![CDATA[echo "<table border=\"0\" cellpadding=\"0\" cellspacing=\"2\" bgcolor=\"#FFFFFF\"
]]><![CDATA[width=\"160\"><tr><td>\n"
]]><![CDATA[."<table border=\"0\" cellpadding=\"0\" cellspacing=\"0\" width=\"160\">\n"
]]><![CDATA[."</table>\n"
]]><![CDATA[."<table border=\"0\" cellpadding=\"2\" cellspacing=\"2\" bgcolor=\"#FFFFFF\"
]]><![CDATA[width=\"100%\">\n"
]]><![CDATA[."<tr><td align=\"center\">\n"
]]><![CDATA[."<font class=\"title\" size=\"1\"><b>Related Websites</b></font>\n"
]]><![CDATA[."</td></tr>\n"
]]><![CDATA[."<tr>\n"
]]><![CDATA[."<td bgcolor=\"#FFFFFF\"><font size=\"1\">";
]]><![CDATA[?>
]]><![CDATA[
]]><![CDATA[<center>
]]><![CDATA[<script type="text/javascript"><!--
]]><![CDATA[google_ad_client = "your client-number";
]]><![CDATA[google_ad_width = 120;
]]><![CDATA[google_ad_height = 600;
]]><![CDATA[google_ad_format = "120x600_as";
]]><![CDATA[google_color_border = "FFFFFF";
]]><![CDATA[google_color_bg = "FFFFFF";
]]><![CDATA[google_color_link = "336699";
]]><![CDATA[google_color_url = "000000";
]]><![CDATA[google_color_text = "000000";
]]><![CDATA[//--></script>
]]><![CDATA[<script type="text/javascript"
]]><![CDATA[src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
]]><![CDATA[</script>
]]><![CDATA[</center>
]]><![CDATA[
]]><![CDATA[<?php
]]><![CDATA[echo "</td>\n"
]]><![CDATA[."</tr>\n"
]]><![CDATA[."</table></td></tr></table>\n"
]]><![CDATA[."<br>\n\n\n";
]]></screen><para>In the above code, you can recognize the Google AdSense Javascript,<indexterm><primary>Javascript</primary></indexterm> also used in <xref linkend="advertisements-in-php-nuke-blocks"> to show AdSense in a <application>PHP-Nuke</application> block,<indexterm><primary>block</primary></indexterm> in the middle of a table layout construction.</para><important>
<title>
Don't forget:
</title>
<para>
Add your Google client number in the AdSense script.
</para>
</important>
</sect2>
<sect2 id="Google-AdSense-on-top-of-php-nuke-module"><title>Google AdSense on top of a <application>PHP-Nuke</application> module</title><para>If you would like to add a 728x90 banner on top of every module,<indexterm><primary>module</primary></indexterm> you can include the AdSense Javascript code in a separate file, call it adsense.php,<indexterm><primary>adsense.php</primary></indexterm> then just include this file from your module (you can also choose a 486*60-banner if you like):</para><para>Put the following code in includes/adsense.php:<indexterm><primary>adsense.php</primary></indexterm></para><screen><![CDATA[<center>
]]><![CDATA[<script type="text/javascript"><!--
]]><![CDATA[google_ad_client = "your client-number";
]]><![CDATA[google_ad_width = 728;
]]><![CDATA[google_ad_height = 90;
]]><![CDATA[google_ad_format = "728x90_as";
]]><![CDATA[google_color_border = "FFFFFF";
]]><![CDATA[google_color_bg = "FFFFFF";
]]><![CDATA[google_color_link = "336699";
]]><![CDATA[google_color_url = "000000";
]]><![CDATA[google_color_text = "000000";
]]><![CDATA[//--></script>
]]><![CDATA[<script type="text/javascript"
]]><![CDATA[src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
]]><![CDATA[</script>
]]><![CDATA[</center>
]]></screen><para>This is nothing else but the well-known Google AdSense Javascript code we have also encountered in <xref linkend="advertisements-in-php-nuke-blocks"> and <xref linkend="Google-AdSense-in-news-module">. Once you have adsense.php in the includes directory, it becomes trivial<indexterm><primary>trivial</primary></indexterm> to use its code in any module you choose: for every module you would like to add the Google AdSense to, look for the following code:</para><screen><![CDATA[include("header.php");
]]></screen><para>and place the following line after that:</para><screen><![CDATA[include("includes/adsense.php");
]]></screen><tip>
<title>
Make some room for long banners
</title>
<para>
Make sure that your module contains the line
</para>
<screen><![CDATA[$index = 0;]]></screen>
<para>
(not necessary if you use 468*60), otherwise you will get the right blocks column too - and this is not nice with a 728*90-banner.
</para>
</tip>
<tip>
<title>
Long AdSense banner in the News module
</title>
<para>
The right place to put the Google AdSense long banner in the News module, is in the modules/News/index.php file,. There, find the line
</para>
<screen><![CDATA[$topic_title = $row_a[topictext];]]></screen>
<para>
and add the line
</para>
<screen><![CDATA[include("includes/adsense.php");]]></screen>
<para>
directly after it (see <ulink url="http://www.luchtzak.be/modules.php?name=Google_AdSense_PHP-Nuke">Google AdSense in PHP-Nuke</ulink>).
</para>
</tip>
</sect2>
</sect1>
<sect1 id="HTML-forms-in-module"><title>How to display HTML forms in a module</title><para>When you have HTML forms in a module,<indexterm><primary>module</primary></indexterm> you may run into problems with passing the values from the form fields to the module itself. Here is just a simple form that you can use as a starting point for your own module with forms - just make a folder named Testing (for instance) in your modules folder, and put an index.<indexterm><primary>index</primary></indexterm>php in it with the following code (see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?topic=12863&amp;forum=42">File doesn't exist error when posting with a form</ulink>):</para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[if (!eregi("modules.php", $PHP_SELF)) {
]]><![CDATA[ die ("You can't access this file directly...");
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[require_once("mainfile.php");
]]><![CDATA[include("header.php");
]]><![CDATA[$module_name = basename(dirname(__FILE__));
]]><![CDATA[
]]><![CDATA[echo "<center><form action=\"modules.php?name=$module_name\" method=\"post\"> "
]]><![CDATA[."Name: <input type=\"text\" name=\"yourname\" size=\"20\"
]]><![CDATA[ value=\"$yourname\">&nbsp;&nbsp;"
]]><![CDATA[."<input type=\"hidden\" name=\"test_input\" value=\"test is good\">"
]]><![CDATA[."<input type=\"submit\" value=\"Submit\"></form></center>";
]]><![CDATA[
]]><![CDATA[if($test_input != "") {
]]><![CDATA[ echo "<br>Form worked, and yourname is $yourname";
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[include("footer.php");
]]><![CDATA[
]]><![CDATA[?>
]]></screen></sect1>
</chapter>
<chapter id="duplicating-PHP-Nuke-modules"><title>Duplicating <application>PHP-Nuke</application> modules</title><para>In some situations, you may find yourself wishing a second, identical module<indexterm><primary>module</primary></indexterm> to the one you already have installed. This requires the following general steps on your part:</para><itemizedlist><listitem><para>Copy the whole module directory, say module1, to a different name, say module2, in the modules folder. You now have modules/module1 and modules/module2, where module1 and module2 are exact directory copies.</para></listitem><listitem><para>Copy all administrative files of module1 (if any). Search for them in admin/modules,<indexterm><primary>modules</primary></indexterm> admin/links and admin/case. The copied files should be in the same directory as the original ones.</para></listitem><listitem><para>Find all tables used by module1. This part may be tricky and involves close examination of the code of all files under modules/module1.</para></listitem><listitem><para>Locate the part(s) of the nuke.sql file (located under the sql directory of the extracted <application>PHP-Nuke</application> package) that creates and populates the tables<indexterm><primary>tables</primary></indexterm> used by module1. Copy that part(s) in a separate file, say nuke2.sql,<indexterm><primary>nuke2.sql</primary></indexterm> and change the names of the tables involved e.g. by adding a &ldquo;2&rdquo; after the names. Run the nuke2.sql file, just as you had ran nuke.sql (see <xref linkend="database-creation">):</para><screen><![CDATA[mysql -u dbuname -p dbname < nuke2.sql
]]></screen></listitem><listitem><para>Inspect the code of all files under modules/module2 and change the table names to reflect the changes in nuke2.sql,<indexterm><primary>nuke2.sql</primary></indexterm> e.g. by adding a &ldquo;2&rdquo; to every table that is specific to module2. Also change any references to administrative files to point to the copied ones. Check the code of the copied administrative files too.</para></listitem><listitem><para>If your module uses any &ldquo;op&rdquo; parameter from the URL,<indexterm><primary>URL</primary></indexterm> you need to edit all the &quot;op&quot; input fields and all the calls to/from those &quot;op's&quot; in the admin/case file.</para></listitem><listitem><para>If the duplicate module should use different texts from the original ones, then you should create the appropriate entries in the language files (under admin/language/, modules/YourModule/ and language/).</para></listitem><listitem><para>Activate module2 from the administration panel (<xref linkend="administration-functions">)</para></listitem></itemizedlist><para>As you can see from the above, duplicating modules can be a fairly complicated enterprise (see also <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=14048">How do I duplicate modules?</ulink>, <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=10394">Multiple Content Modules</ulink>). In what follows, we will demonstrate this general procedure in a real world example - duplicating the FAQ module.<indexterm><primary>module</primary></indexterm></para><sect1 id="duplicating-PHP-Nuke-FAQ-module"><title>Duplicating the <application>PHP-Nuke</application> FAQ module</title><para>Suppose you would like to have two FAQ modules.<indexterm><primary>modules</primary></indexterm> You might of course ask why on earth you would want such a complication<indexterm><primary>complication</primary></indexterm> in your <application>PHP-Nuke</application> site, but if you recall that <application>PHP-Nuke</application> lets you decide for each module individually whether to all visitors, only registered ones, or only administrators to view it, you will find out that two identical FAQ modules would be a simple way to have two FAQs,<indexterm><primary>FAQs</primary></indexterm> one only for administrators and one for all users. </para><para>We will now follow the steps outlined above for the purpose of duplicating the FAQ module:<indexterm><primary>module</primary></indexterm></para><itemizedlist><listitem><para>We copy the whole directory modules/FAQ to modules/Admin_FAQ<indexterm><primary>FAQ</primary></indexterm></para></listitem><listitem><para>We also copy:<indexterm><primary>copy</primary></indexterm></para><itemizedlist><listitem><para>admin/modules/adminfaq.<indexterm><primary>faq</primary></indexterm>php to admin/modules/adminfaq2.php,</para></listitem><listitem><para>admin/links/links.faq.<indexterm><primary>faq</primary></indexterm>php to admin/links/links.faq2.php and</para></listitem><listitem><para>admin/case/case.adminfaq.<indexterm><primary>faq</primary></indexterm>php to admin/case/case.adminfaq2.php.</para></listitem></itemizedlist></listitem><listitem><para>Code inspection reveals that the only tables used by the FAQ module are faqAnswer and faqCategories.<indexterm><primary>Categories</primary></indexterm></para></listitem><listitem><para>The relevant part of nuke.sql that creates and populates faqAnswer and faqCategories is easily located. After we append a &ldquo;2&rdquo; at the table names and copy it to nuke2.sql,<indexterm><primary>nuke2.sql</primary></indexterm> the latter will have the following content:</para><screen><![CDATA[#
]]><![CDATA[# Table structure for table `nuke_faqAnswer2`
]]><![CDATA[#
]]><![CDATA[
]]><![CDATA[CREATE TABLE nuke_faqAnswer2 (
]]><![CDATA[ id tinyint(4) NOT NULL auto_increment,
]]><![CDATA[ id_cat tinyint(4) NOT NULL default '0',
]]><![CDATA[ question varchar(255) default ",
]]><![CDATA[ answer text,
]]><![CDATA[ PRIMARY KEY (id),
]]><![CDATA[ KEY id (id),
]]><![CDATA[ KEY id_cat (id_cat)
]]><![CDATA[) TYPE=MyISAM;
]]><![CDATA[#
]]><![CDATA[# Dumping data for table `nuke_faqAnswer2`
]]><![CDATA[#
]]><![CDATA[# --------------------------------------------------------
]]><![CDATA[#
]]><![CDATA[# Table structure for table `nuke_faqCategories2`
]]><![CDATA[#
]]><![CDATA[CREATE TABLE nuke_faqCategories2 (
]]><![CDATA[ id_cat tinyint(3) NOT NULL auto_increment,
]]><![CDATA[ categories varchar(255) default NULL,
]]><![CDATA[ flanguage varchar(30) NOT NULL default ",
]]><![CDATA[ PRIMARY KEY (id_cat),
]]><![CDATA[ KEY id_cat (id_cat)
]]><![CDATA[) TYPE=MyISAM;
]]><![CDATA[#
]]><![CDATA[# Dumping data for table `nuke_faqCategories2`
]]><![CDATA[#
]]><![CDATA[# --------------------------------------------------------
]]><![CDATA[
]]></screen></listitem><listitem><para>We run the nuke2.sql file from the MySQL prompt::</para><screen><![CDATA[mysql -u dbuname -p dbname < nuke2.sql
]]></screen></listitem><listitem><para>This will create the nuke_faqAnswer2 and nuke_faqCategories2 tables in the database dbname (remember to replace dbuname and dbname with their real values from your config.<indexterm><primary>config</primary></indexterm>php!). Since the FAQ module does not come with preset categories and answers, the tables are not populated with data.<indexterm><primary>data</primary></indexterm></para></listitem><listitem><para>We edit all files under modules/Admin-FAQ and also the administrative files admin/modules/adminfaq2.php, admin/links/links.faq2.php and admin/case/case.<indexterm><primary>case</primary></indexterm>adminfaq2.php: we change all references to faqAnswer or faqCategories to faqAnswer2<indexterm><primary>faqAnswer2</primary></indexterm> and faqCategories2 respectively.</para></listitem><listitem><para>In admin/case/case.adminfaq.<indexterm><primary>faq</primary></indexterm>php we change </para><screen><![CDATA[include ("admin/modules/adminfaq.php");
]]></screen><para>to </para><screen><![CDATA[include ("admin/modules/adminfaq2.php");
]]></screen></listitem></itemizedlist><para>Finally, we activate the Admin-FAQ module and specify that it can be viewed only by administrators.</para><caution>
<title>
Don't forget the "op"s!
</title>
<para>
If you want your duplicate module to perform slightly different functions than the original one, there is no way around to creating duplicate "op" functions to be called from the "switch($op)" part of the admin file. In our example, this would mean that we would change
</para>
<screen>
<![CDATA[switch($op) {]]>
<![CDATA[]]>
<![CDATA[ case "FaqCatSave":]]>
<![CDATA[ FaqCatSave($id_cat, $categories, $flanguage); /* Multilingual Code : added variable */]]>
<![CDATA[ break;]]>
<![CDATA[]]>
<![CDATA[ case "FaqCatGoSave":]]>
<![CDATA[ FaqCatGoSave($id, $question, $answer);]]>
<![CDATA[ break;]]>
<![CDATA[]]>
<![CDATA[ case "FaqCatAdd":]]>
<![CDATA[ FaqCatAdd($categories, $flanguage); /* Multilingual Code : added variable */]]>
<![CDATA[ break;]]>
<![CDATA[]]>
<![CDATA[ case "FaqCatGoAdd":]]>
<![CDATA[ FaqCatGoAdd($id_cat, $question, $answer);]]>
<![CDATA[ break;]]>
<![CDATA[]]>
<![CDATA[ case "FaqCatEdit":]]>
<![CDATA[ FaqCatEdit($id_cat);]]>
<![CDATA[ break;]]>
<![CDATA[]]>
<![CDATA[ case "FaqCatGoEdit":]]>
<![CDATA[ FaqCatGoEdit($id);]]>
<![CDATA[ break;]]>
<![CDATA[]]>
<![CDATA[ case "FaqCatDel":]]>
<![CDATA[ FaqCatDel($id_cat, $ok);]]>
<![CDATA[ break;]]>
<![CDATA[]]>
<![CDATA[ case "FaqCatGoDel":]]>
<![CDATA[ FaqCatGoDel($id, $ok);]]>
<![CDATA[ break;]]>
<![CDATA[]]>
<![CDATA[ case "FaqAdmin":]]>
<![CDATA[ FaqAdmin();]]>
<![CDATA[ break;]]>
<![CDATA[]]>
<![CDATA[ case "FaqCatGo":]]>
<![CDATA[ FaqCatGo($id_cat);]]>
<![CDATA[ break;]]>
<![CDATA[}]]>
<![CDATA[]]>
<![CDATA[} else {]]>
<![CDATA[ echo "Access Denied";]]>
<![CDATA[}]]>
</screen
<para>in the admin/modules/adminfaq.php file, to: </para>
<screen>
<![CDATA[switch($op) {]]>
<![CDATA[]]>
<![CDATA[ case "FaqCatSave2":]]>
<![CDATA[ FaqCatSave2($id_cat, $categories, $flanguage); /* Multilingual Code : added variable */]]>
<![CDATA[ break;]]>
<![CDATA[]]>
<![CDATA[ case "FaqCatGoSave2":]]>
<![CDATA[ FaqCatGoSave2($id, $question, $answer);]]>
<![CDATA[ break;]]>
<![CDATA[]]>
<![CDATA[ case "FaqCatAdd2":]]>
<![CDATA[ FaqCatAdd2($categories, $flanguage); /* Multilingual Code : added variable */]]>
<![CDATA[ break;]]>
<![CDATA[]]>
<![CDATA[ case "FaqCatGoAdd2":]]>
<![CDATA[ FaqCatGoAdd2($id_cat, $question, $answer);]]>
<![CDATA[ break;]]>
<![CDATA[]]>
<![CDATA[ case "FaqCatEdit2":]]>
<![CDATA[ FaqCatEdit2($id_cat);]]>
<![CDATA[ break;]]>
<![CDATA[]]>
<![CDATA[ case "FaqCatGoEdit2":]]>
<![CDATA[ FaqCatGoEdit2($id);]]>
<![CDATA[ break;]]>
<![CDATA[]]>
<![CDATA[ case "FaqCatDel2":]]>
<![CDATA[ FaqCatDel2($id_cat, $ok);]]>
<![CDATA[ break;]]>
<![CDATA[]]>
<![CDATA[ case "FaqCatGoDel2":]]>
<![CDATA[ FaqCatGoDel2($id, $ok);]]>
<![CDATA[ break;]]>
<![CDATA[]]>
<![CDATA[ case "FaqAdmin2":]]>
<![CDATA[ FaqAdmin2();]]>
<![CDATA[ break;]]>
<![CDATA[]]>
<![CDATA[ case "FaqCatGo2":]]>
<![CDATA[ FaqCatGo2($id_cat);]]>
<![CDATA[ break;]]>
<![CDATA[}]]>
<![CDATA[]]>
<![CDATA[} else {]]>
<![CDATA[ echo "Access Denied";]]>
<![CDATA[}]]>
</screen>
<para>
and then program the new functionality into the new functions (the ones with the 2 suffix in their name).
</para>
</caution>
</sect1>
</chapter>
<chapter id="security"><title>Security </title><epigraph>
<para>
Aut inveniam viam aut faciam.
</para>
<para>
I will either find a way or make one.
</para>
</epigraph>
<sect1 id="how-secure-is-php-nuke"><title>How secure is PHP-Nuke?</title><para>If you run the security audit tool <ulink url="http://www.nessus.org">nessus</ulink> against a host running PHP-Nuke, you will get the following:</para><blockquote><para>The remote host is running a copy of <application>PHP-Nuke</application>.</para><para>Given the insecurity history of this package, the Nessus team recommands that you do not use it but use something else instead, as security was clearly not in the mind of the persons who wrote it.</para><para>The author of <application>PHP-Nuke</application> (Francisco Burzi) even started to rewrite the program from scratch,<indexterm><primary>scratch</primary></indexterm> given the huge number of vulnerabilities (<ulink url="http://www.phpnuke.org/modules.php?name=News&amp;file=article&amp;sid=5640">Clarifications on a possible rewrite of PHP-Nuke</ulink>).</para><para>Solution : De-install this package and use something else</para><para>Risk factor : High</para></blockquote><para>Uh? <inlinemediaobject> <![ %output.print.png; [ <imageobject><imagedata fileref="./images/icon_eek.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject><imagedata fileref="icon_eek.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject><imagedata fileref="./images/icon_eek.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject><imagedata fileref="icon_eek.bmp" format="BMP"> </imageobject> ]]> <textobject><phrase>eek!</phrase> </textobject></inlinemediaobject> Does this mean we have throw away PHP-Nuke? Why is nessus saying this? </para>
<para>The link given by nessus above, contains Francisco's thoughts on the furure of PHP-Nuke, provoked by a recent series of security holes at that time. How was Francisco thinking to cope with the security issues? In that article<indexterm><primary>article</primary></indexterm> regarding <ulink url="http://www.phpnuke.org/modules.php?name=News&amp;file=article&amp;sid=5640">Clarifications on a possible rewrite of PHP-Nuke</ulink>, Franzisco considers the following possibility as the first one that comes to his mind when contemplating on how to proceed:</para><blockquote><para>1) The new code will be closed. This means that script kiddies should get a computer science master or PhD before hacking it. This will reduce the security issues. From time to time, a security test will be made on the code to catch those bugs and fix them.</para></blockquote><para>This is a well-known method of securing your programs - it is called <ulink url="http://www.wikipedia.org/wiki/Security_by_obscurity">security by obscurity</ulink>. A system relying on security by obscurity may have theoretical or actual security vulnerabilities,<indexterm><primary>vulnerabilities</primary></indexterm> but its owners or designers believe that the flaws are not known, and that attackers are unlikely to find them.</para><para>Would you trust such a system to be secure? Would you run a Fortune 500 website on top of it? It is in this light that you have to interpret nessus' warning above. Relying on security by obscurity as a strategy for PHP-Nuke, be it only in a thought experiment, will not persuade the security experts at nessus.<indexterm><primary>nessus</primary></indexterm>org. Because in the cryptography world, the reverse of security by obscurity<indexterm><primary>obscurity</primary></indexterm> is believed to be true: <ulink url="http://www.wikipedia.org/wiki/Kerckhoffs%27_principle">Kerckhoffs' principle</ulink> from the late 1880s, which states that system designers should assume that the entire design of a security system is known to all attackers,<indexterm><primary>attackers</primary></indexterm> with the exception of cryptographic key secrets.</para><para>In practice, operators of systems that rely on security by obscurity often keep the fact that their system is broken secret, so as not to destroy confidence in their service or product (see <ulink url="http://www.wikipedia.org/wiki/Security_by_obscurity">security by obscurity</ulink>). Examples of such systems are the <productname>Windows</productname> &ldquo;operating system<indexterm><primary>system</primary></indexterm>&rdquo; and the IIS web server.<indexterm><primary>server</primary></indexterm> According to its creator above, <application>PHP-Nuke</application> may join them in the future. This has not kept large firms from using these products for their web presence, though. It is therefore up to you how you interpret nessus' warning and Francisco's tendency to resort to controversial security principles.</para><para>People have commented on Francisco's thoughts in that article,<indexterm><primary>article</primary></indexterm> the sleepless nights trying to close the security holes that were afflicting thousands<indexterm><primary>thousands</primary></indexterm> of <application>PHP-Nuke</application> sites were over and, after some sleep and thoughtful weighting of all the factors involved, Francisco published an <ulink url="http://www.phpnuke.org/modules.php?name=News&amp;file=article&amp;sid=5647&amp;mode=thread&amp;order=0&amp;thold=0">Update and answer to all your nice comments</ulink>. In this update,<indexterm><primary>date</primary></indexterm> we read that the to do list for <application>PHP-Nuke</application> starts as follows:</para><blockquote><para>1) Release the 6.5 version</para><para>2) Start catching security bugs,<indexterm><primary>bugs</primary></indexterm> sql injections holes, etc and fixing it.</para><para>3) Recode some parts of the core system to properly check variables against malicious code.</para><para>4) Reorganization of some html code</para><para>etc.</para></blockquote><para>Unfortunately, reading the above can give one the impression that the release of an intermediate version (priority 1) is more important than catching security bugs and properly checking against malicious code (priorities 2 and 3 respectively), even if this may not be really the case in the author's mind.<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_frown.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_frown.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_frown.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_frown.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
<para>In fact, Francisco, does care about security,<indexterm><primary>security</primary></indexterm> as he confesses in another article on the <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=13048">History of <application>PHP-Nuke</application> and Post-Nuke</ulink>:</para><blockquote><para>About security.<indexterm><primary>security</primary></indexterm>.. Many people can think that I don't care about security.<indexterm><primary>security</primary></indexterm>.. I care,<indexterm><primary>care</primary></indexterm> a lot. But what I don't do is to publish &quot;exploits&quot; in my site about my software...Paul is the perfect proof of the above affirmation, he's a direct witness of my interest on this matter... is secret yes, but there is interest.</para></blockquote><para>Should nessus' warning prevent you from deploying <application>PHP-Nuke</application> on your site? This is a question that only you can answer. In the Web there are multiple truths that can coexist one besides the other. In <ulink url="http://philip.greenspun.com/panda/suck">Envisioning a Site That Won't Be Featured In suck.com</ulink>, Philip Greenspun writes about one-truth cultures:<indexterm><primary>cultures</primary></indexterm></para><blockquote><para>Oral cultures do not share this belief. Knowledge is open-ended.<indexterm><primary>open-ended</primary></indexterm> People may hold differing opinions without one person being wrong. There is not necessarily one truth; there may be many truths. Though he didn't grow up in an oral culture, Shakespeare knew this. Watch Troilus and Cressida and its five perspectives on the nature of a woman's love. Try to figure out which perspective Shakespeare thinks is correct.</para></blockquote><para>In deciding how secure <application>PHP-Nuke</application> is for you, you have to find your own truth. Let's have a look at PHP-Nuke's security record, since this is what nessus<indexterm><primary>nessus</primary></indexterm> mentions as a prominent reason not to use it.</para></sect1>
<sect1 id="security-record-software-popularity"><title>The impact of bad security record on software popularity </title><para><ulink url="http://www.sendmail.org">sendmail</ulink>, the leading Mail Transport Agent in use today, was written at a time when security was not a big issue. Internet was not as widespread as today and the netizens were kinder to each other. To use nessus' words,<indexterm><primary>words</primary></indexterm> &ldquo;security was clearly not in the mind of the persons who wrote it&rdquo;. Sendmail's security record is legendary (one is tempted to say &ldquo;abysmal&rdquo;), see this list of <ulink url="http://cr.yp.to/maildisasters/sendmail.html">Sendmail desasters</ulink>, which only covers the period from 1993 through 1997. There was a time when sysadmins had to get used to weekly security patches from the sendmail author and even joked about that. </para><para>Did this prevent the whole world from using sendmail?<indexterm><primary>sendmail</primary></indexterm> Not at all. Did this prevent Fortune 500 companies from organising their mail systems with sendmail?<indexterm><primary>sendmail</primary></indexterm> Doesn't seem so. I wonder if the nessus folks would issue the same warning for sendmail<indexterm><primary>sendmail</primary></indexterm> too (didn't check, I must admit): </para><blockquote><para>The remote host is running a copy of Sendmail.<indexterm><primary>Sendmail</primary></indexterm> Given the insecurity history of this package, the Nessus team recommends that you do not use it but use something else instead, as security was clearly not in the mind of the persons who wrote it.</para></blockquote><para>Other software, like vBulletin, Iconboard,<indexterm><primary>Iconboard</primary></indexterm> YaBB or Post-Nuke have shown security problems too. Even hardware is not safe from vulnerabilities today, since it may be running on faulty firmware.<indexterm><primary>firmware</primary></indexterm> See <ulink url="http://www.nukecops.com/article46.html">How secure is PHP-Nuke?</ulink> for a long list of links on such examples. </para><para>You may have a different opinion on sendmail's merits, but obviously its security record did not harm its popularity that much. And we didn't go that far as to examine this effect on even more popular software, like <productname>Windows</productname>. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> That's why, once again, you have to weigh nessus' warning with your own personal &ldquo;weight factor&rdquo;.</para>
</sect1>
<sect1 id="common-php-nuke-security-vulnerabilities"><title>Common <application>PHP-Nuke</application> security vulnerabilities</title><para>It's instructive to take the time and have a look at <ulink url="http://www.secunia.com/advisories/search/date/?task=search&amp;search=php-nuke&amp;vuln_title=1&amp;vuln_software_os=1&amp;vuln_bodytext=1&amp;vuln_cve=1">PHP-Nuke's list of vulnerabilities</ulink> (see <xref linkend="tab-security-vulnerabilities">). Even a superficial inspection reveals some common vulnerability patterns:<indexterm><primary>patterns</primary></indexterm></para><itemizedlist><listitem><para>Cross-site scripting (<xref linkend="cross-site-scripting-with-php-nuke">)</para></listitem><listitem><para>SQL injection (<xref linkend="SQL-injection-with-php-nuke">)</para></listitem><listitem><para>Path disclosure (<xref linkend="path-disclosure-with-php-nuke">)</para></listitem><listitem><para>Cross-site tracing (<xref linkend="cross-site-tracing-with-php-nuke">)</para></listitem></itemizedlist><para>In the following we will examine them in more detail.</para><para><table id="tab-security-vulnerabilities"><title>List of <application>PHP-Nuke</application> security vulnerabilities</title><tgroup cols="2" colsep="1" rowsep="1">
<colspec colname="col0" align="left">
<colspec colname="col1" align="left">
<tbody>
<row>
<entry align="left" valign="top"><para>Description</para></entry>
<entry align="left" valign="top"><para>Date</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><ulink url="http://www.secunia.com/advisories/10040/">PHP-Nuke Path Disclosure Vulnerability</ulink></para></entry>
<entry align="left" valign="top"><para>21.10.2003</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><ulink url="http://www.secunia.com/advisories/9307/">Splatt Forum Cross-Site Scripting Vulnerability</ulink></para></entry>
<entry align="left" valign="top"><para>19.07.2003</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><ulink url="http://www.secunia.com/advisories/8801/">PHP-Nuke SQL injection</ulink></para></entry>
<entry align="left" valign="top"><para>19.05.2003</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><ulink url="http://www.secunia.com/advisories/8716/">Splatt Forum Cross Site Scripting</ulink></para></entry>
<entry align="left" valign="top"><para>02.05.2003</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><ulink url="http://www.secunia.com/advisories/8662/">PHP-Nuke Cross-Site Scripting</ulink></para></entry>
<entry align="left" valign="top"><para>25.04.2003</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><ulink url="http://www.secunia.com/advisories/8478/">PHP-Nuke Cross-Site Scripting</ulink></para></entry>
<entry align="left" valign="top"><para>01.04.2003</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><ulink url="http://www.secunia.com/advisories/8417/">PHP-Nuke SQL Injection</ulink></para></entry>
<entry align="left" valign="top"><para>26.03.2003</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><ulink url="http://www.secunia.com/advisories/8341/">PHP-Nuke Referer Cross-Site Scripting</ulink></para></entry>
<entry align="left" valign="top"><para>19.03.2003</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><ulink url="http://www.secunia.com/advisories/8321/">PHP-Nuke Path Disclosure</ulink></para></entry>
<entry align="left" valign="top"><para>18.03.2003</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><ulink url="http://www.secunia.com/advisories/8245/">PHP-Nuke Multiple SQL Injection Vulnerabilities</ulink></para></entry>
<entry align="left" valign="top"><para>07.03.2003</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><ulink url="http://www.secunia.com/advisories/8144/">PHP-Nuke Multiple SQL Injection Vulnerabilities</ulink></para></entry>
<entry align="left" valign="top"><para>25.02.2003</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><ulink url="http://www.secunia.com/advisories/7993/">PHP Nuke Avatar Scriptcode Injection</ulink></para></entry>
<entry align="left" valign="top"><para>04.02.2003</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><ulink url="http://www.secunia.com/advisories/7776/">PHP-Nuke mail CRLF injection</ulink></para></entry>
<entry align="left" valign="top"><para>23.12.2002</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><ulink url="http://www.secunia.com/advisories/7731/">PHP-Nuke execution of arbitrary code</ulink></para></entry>
<entry align="left" valign="top"><para>17.12.2002</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><ulink url="http://www.secunia.com/advisories/7736/">PHP-Nuke Cross Site Scripting</ulink></para></entry>
<entry align="left" valign="top"><para>17.12.2002</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><ulink url="http://www.secunia.com/advisories/7595/">PHP-Nuke Cross Site Scripting</ulink></para></entry>
<entry align="left" valign="top"><para>25.11.2002</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><ulink url="http://www.secunia.com/advisories/7430/">PHP-Nuke SQL injection resets passwords</ulink></para></entry>
<entry align="left" valign="top"><para>01.11.2002</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><ulink url="http://www.secunia.com/advisories/7271/">PHP-Nuke Cross Site Scripting</ulink></para></entry>
<entry align="left" valign="top"><para>10.10.2002</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><ulink url="http://www.secunia.com/advisories/7153/">Cross Site Scripting holes in Xoops, PHP-Nuke, NPDS, daCode, Drupal and phpWebSite</ulink></para></entry>
<entry align="left" valign="top"><para>24.09.2002</para></entry>
</row>
</tbody>
</tgroup></table></para><sect2 id="cross-site-scripting-with-php-nuke"><title>Cross-site scripting with PHP-Nuke</title><para>A CSS vulnerability is caused by the failure of a site to validate user input before returning it to the client s web-browser. The essence of cross-site scripting is that an intruder causes a legitimate<indexterm><primary>legitimate</primary></indexterm> web server to send a page to a victim's browser that contains malicious<indexterm><primary>malicious</primary></indexterm> script or HTML of the intruder's choosing. The malicious script runs with the privileges of a legitimate script originating from the legitimate web server (see <ulink url="http://www.cert.org/archive/pdf/cross_site_scripting.pdf">Cross-Site Scripting Vulnerabilities</ulink>). By failing to validate user input, the vulnerable site makes it possible for a malicious user to execute (&ldquo;inject<indexterm><primary>inject</primary></indexterm>&rdquo;) a script in the context of that site's process.</para><para>Here are some known examples of cross-site scripting with PHP-Nuke:</para><itemizedlist><listitem><para>When a user posts messages, special characters are not stripped making it possible to inject malicious script code. The user types in a forum message </para><screen><![CDATA[Some test text for fun <script>alert(document.cookie);</script> some more text..
]]></screen><para>the text is not checked for the presence of a script - and the script is executed in the victim's browser, who thinks it is a safe forum text from a trusted <application>PHP-Nuke</application> site. (see <ulink url="http://www.secunia.com/advisories/8716/">Splatt Forum Cross Site Scripting</ulink>).</para></listitem><listitem><para>In a search field, the user types</para><screen><![CDATA[<script>alert(document.cookie);</script>
]]></screen><para>The search text is displayed in the results page without being validated. The result: a script is again executed in the victim's browser (see <ulink url="http://www.secunia.com/advisories/8716/">Splatt Forum Cross Site Scripting</ulink>, <ulink url="http://www.secunia.com/advisories/7595/">PHP-Nuke Cross Site Scripting</ulink>).</para></listitem><listitem><para>In a forum post, a user types</para><screen><![CDATA[<html>
]]><![CDATA[<body>
]]><![CDATA[<script>
]]><![CDATA[<!-- Modify here -->
]]><![CDATA[var address='http://www.splatt.it/gate.html?mop=modload&name=Forums&file=newtopic';
]]><![CDATA[</script>
]]><![CDATA[<!-- Exploit form -->
]]><![CDATA[<script>
]]><![CDATA[document.write("<form action="+address+" method='post' name='coolsus'>");
]]><![CDATA[</script>
]]><![CDATA[Forum Number: <input type=text name=forum value=1 size=3><br>
]]><![CDATA[Username: <input CLASS=textbox TYPE="TEXT" NAME="username"
]]><![CDATA[ SIZE="25" MAXLENGTH="40"><br>
]]><![CDATA[Password: <input CLASS=textbox TYPE="PASSWORD" NAME="password"
]]><![CDATA[ SIZE="25" MAXLENGTH="25"><br>
]]><![CDATA[Subject: <input CLASS=textbox TYPE="TEXT" NAME="subject"
]]><![CDATA[ SIZE="75" MAXLENGTH="75"><br>
]]><![CDATA[Message:<br><textarea name="message" rows="10" cols="75"
]]><![CDATA[ wrap="VIRTUAL"></textarea><br>
]]><![CDATA[<input type=hidden name=bbcode value=0>
]]><![CDATA[<input type=hidden name=smile value=0>
]]><![CDATA[<input type=hidden name=notify value=0>
]]><![CDATA[
]]><![CDATA[<b>Inject code:</b> <input type=text name=image_subject
]]><![CDATA[value='icon1.gif">HTML CODE<!-- "' size=100><br>
]]><![CDATA[
]]><![CDATA[<input type="submit" name="submit" value=submit class="Button">
]]><![CDATA[</form>
]]><![CDATA[</body>
]]><![CDATA[</html>
]]></screen><para>The input is not checked if it contains malicious code, the script is executed in a user's browser when viewed. Successful exploitation can result in disclosure of various information<indexterm><primary>information</primary></indexterm> (eg. cookie-based authentication information) associated with the site running Splatt Forum or inclusion of malicious content, which the user thinks is part of the real website (see <ulink url="http://www.secunia.com/advisories/9307/">Splatt Forum Cross-Site Scripting Vulnerability</ulink>).</para></listitem><listitem><para>Due to insufficient validation of user input used in an attribute inside a tag, arbitrary script code can be executed by a malicious user. The characters &lt; and &gt; are filtered, but <application>PHP-Nuke</application> neglects to filter out &ldquo; characters. A malicious person can exploit this to execute arbitrary script code in a user's browser session by including it in either the profile,<indexterm><primary>profile</primary></indexterm> comments, or a private message, where one has only to type something like</para><screen><![CDATA[<a href="http://" onclick="alert('test')">http://" onclick="alert('test')</a>
]]></screen><para>to provoke this behaviour (see <ulink url="http://www.secunia.com/advisories/8662/">PHP-Nuke Cross-Site Scripting</ulink>).</para></listitem><listitem><para>By posting a forum message with a title like: </para><screen><![CDATA[">&lt;script&gt;evil_code;&lt;/script&gt;
]]></screen><para>the title will be returned by blocks/block-Forum.<indexterm><primary>Forum</primary></indexterm>php as valid html or script code to the users viewing the message (see <ulink url="http://www.secunia.com/advisories/8478/">PHP-Nuke Cross-Site Scripting</ulink>).</para></listitem><listitem><para>Input supplied to the $referer variable is not filtered when inserted into the backend database,<indexterm><primary>base</primary></indexterm> which makes it possible to include arbitrary script code. When viewed by an administrator,<indexterm><primary>administrator</primary></indexterm> the script code will be executed automatically in the administrator's browser session and could eg. steal the authentication cookie associated with the website,<indexterm><primary>website</primary></indexterm> which contains the administrator's username and password (see <ulink url="http://www.secunia.com/advisories/8341/">PHP-Nuke Referer Cross-Site Scripting</ulink>).</para></listitem><listitem><para>Using the following manipulated addresses</para><screen><![CDATA[modules/Forums/bb_smilies.php?name=code
]]><![CDATA[modules/Forums/bb_smilies.php?Default_Theme=code
]]><![CDATA[modules/Forums/bb_smilies.php?site_font=}--></style>code
]]><![CDATA[modules/Forums/bb_smilies.php?bgcolor1=">code
]]></screen><para>where &quot;code&quot; is a malicious code, a user can execute this code in a viewer's browser (see <ulink url="http://www.secunia.com/advisories/7736/">PHP-Nuke Cross Site Scripting</ulink>).</para></listitem></itemizedlist><para>As you can see from the above examples, the only remedy to cross-site scripting<indexterm><primary>scripting</primary></indexterm> problems is to write <acronym>PHP</acronym> code that validates user input (or, if you are the &ldquo;viewer&rdquo;, disable scripting altogether, although even this will not prevent the injection of malicious HTML,<indexterm><primary>HTML</primary></indexterm> see <ulink url="http://www.cert.org/archive/pdf/cross_site_scripting.pdf">Cross-Site Scripting Vulnerabilities</ulink>).</para></sect2>
<sect2 id="SQL-injection-with-php-nuke"><title>SQL injection with PHP-Nuke</title><para>Interaction with relational databases takes place through a textual language, the Structured Query Language ('SQL'). The most recent standard is ANSI SQL-92 and forms the basis around which most SQL dialects are based today. See <ulink url="http://www-dbs.inf.ethz.ch/~isk/WS_97/syntax_diagramme/">SQL syntax diagrams</ulink> for a visualization of SQL syntax.<indexterm><primary>syntax</primary></indexterm> Data extraction from the database takes place through a 'query', which is a collection of SQL statements.<indexterm><primary>statements</primary></indexterm> An SQL query returns the data in a so-called 'result set'. </para><para>SQL statements are divided into two general categories: those that can modify the structure (Data Definition Language statements,<indexterm><primary>statements</primary></indexterm> or 'DDL') and those that can manipulate the contents of databases (Data Manipulation Language<indexterm><primary>Language</primary></indexterm> statements,<indexterm><primary>statements</primary></indexterm> or 'DML'). SQL Injection occurs when an attacker is able to insert a series of SQL<indexterm><primary>SQL</primary></indexterm> statements into a 'query' by manipulating data input into an application<indexterm><primary>application</primary></indexterm> (see <ulink url="http://www.nextgenss.com/papers/advanced_sql_injection.pdf">Advanced SQL Injection in SQLServer Applications</ulink>).</para><para>The typical scenario of an SQL Injection goes like this: an SQL statement like (taken from mainfile.php)</para><screen><![CDATA[SELECT active FROM ".$prefix."_modules WHERE title='$module'
]]></screen><para>is used to retrieve the 'active' column from the 'nuke_modules' table (assuming that $prefix is set to 'nuke' in config.php,<indexterm><primary>config.php</primary></indexterm> see <xref linkend="config-php-file">), returning in the 'result set' only the row that matches the module $module.<indexterm><primary>module</primary></indexterm> An important point to note here is that the string literal '$module' is delimited with single quotes.<indexterm><primary>quotes</primary></indexterm> Presuming that $module is taken from the URL or from user input and was not subjected to further scrutiny,<indexterm><primary>scrutiny</primary></indexterm> one could use a &ldquo;module name&rdquo; of </para><screen><![CDATA[' UNION ALL SELECT user_password FROM nuke_users WHERE "='
]]></screen><para>and the 'query string' would become: </para><screen><![CDATA[SELECT active FROM ".$prefix."_modules
]]><![CDATA[WHERE title=" UNION ALL SELECT user_password FROM nuke_users WHERE "="
]]></screen><para>The database server would execute the first part </para><screen><![CDATA[SELECT active FROM ".$prefix."_modules WHERE title="
]]></screen><para>and would find no modules with empty title.<indexterm><primary>title</primary></indexterm> It would then combine<footnote><para>this kind of SQL injection needs a database capable of understanding the UNION clause (for MySQL at least v. 4.x)</para></footnote> this empty result set with the outcome of </para><screen><![CDATA[SELECT user_password FROM nuke_users WHERE "="
]]></screen><para>which selects all passwords (since the WHERE clause is tautologically true, comparing an empty string with itself), returning the &ldquo;cartesian product&rdquo; (UNION) of the two - i.e. the set of all passwords.<indexterm><primary>words</primary></indexterm> If the outcome of such a query is supposed to be printed somewhere, the user will be able to see sensitive information.<indexterm><primary>information</primary></indexterm></para><para>If the &ldquo;module name&rdquo; passed on unchecked were</para><screen><![CDATA[' ; DROP TABLES WHERE "='
]]></screen><para>the consequences would be catastrophic: the database server would execute</para><screen><![CDATA[SELECT active FROM ".$prefix."_modules WHERE title=" ; DROP TABLES WHERE "="
]]></screen><para>Depending on the actual SQL query,<indexterm><primary>query</primary></indexterm> you may have to try some of these possibilities for the WHERE clause:<indexterm><primary>clause</primary></indexterm></para><screen><![CDATA[' or 1=1--
]]><![CDATA[" or 1=1--
]]><![CDATA[or 1=1--
]]><![CDATA[' or 'a'='a
]]><![CDATA[" or "a"="a
]]><![CDATA[') or ('a'='a
]]></screen><para>instead of</para><screen><![CDATA["='
]]></screen><para>The general rule is that to &quot;break out&quot; of the quotes and manipulate the SQL query, while maintaining valid SQL syntax,<indexterm><primary>syntax</primary></indexterm> your query string must start with a quote and end in a WHERE clause that needs a query appended to it (see <ulink url="http://www.spidynamics.com/papers/SQLInjectionWhitePaper.pdf">SQL Injection</ulink>).</para><para>In PHP-Nuke, SQL injection has been reported in the following vulnerabilities:<indexterm><primary>vulnerabilities</primary></indexterm></para><itemizedlist><listitem><para>The &quot;cid&quot; parameter isn't properly verified in the &quot;Downloads&quot;<indexterm><primary>Downloads</primary></indexterm> module. This can be exploited to manipulate the SQL query and may potentially allow bypassing authentication or reveal sensitive information (see <ulink url="http://www.secunia.com/advisories/9994/">PHP-Nuke SQL Injection Vulnerability</ulink>).</para></listitem><listitem><para>Numeric values in the Web_Links module aren't validated before they are used in SQL queries.<indexterm><primary>queries</primary></indexterm> Example:</para><screen><![CDATA[/modules.php?op=modload&name=Web_Links&file=index&l_op=viewlink&cid=2%20malicious_SQL
]]></screen><para>(see <ulink url="http://www.secunia.com/advisories/8801/">PHP-Nuke SQL injection</ulink>). You wonder how malicious_SQL might look like? Here is a real world example from my web server logs:</para><screen><![CDATA[/modules.php?name=Web_Links&l_op=viewlink&cid=2
]]><![CDATA[%20UNION%20select%20counter,%20pwd,%20aid%20FROM%20nuke_authors%20
]]></screen></listitem><listitem><para>Several input validation errors, which could be exploited by malicious people to manipula te existing SQL queries by conducting SQL injection attacks against the application,<indexterm><primary>application</primary></indexterm> see <ulink url="http://www.secunia.com/advisories/8417/">PHP-Nuke SQL Injection</ulink>.</para></listitem><listitem><para>Input validation errors in the modules &quot;Members_List&quot; and &quot;Your_Account&quot;<indexterm><primary>Your_Account</primary></indexterm>, which can be exploited by conducting a SQL injection attack,<indexterm><primary>attack</primary></indexterm> see <ulink url="http://www.secunia.com/advisories/8245/">PHP-Nuke Multiple SQL Injection Vulnerabilities</ulink>.</para></listitem><listitem><para>Vulnerabilities can be exploited to manipulate existing SQL queries,<indexterm><primary>queries</primary></indexterm> which can result in disclosure of the Admin user's password hash.<indexterm><primary>hash</primary></indexterm> This can afterwards be used to gain administrative priviliges for PHP-Nuke, see <ulink url="http://www.secunia.com/advisories/8144/">PHP-Nuke Multiple SQL Injection Vulnerabilities</ulink>.</para></listitem></itemizedlist></sect2>
<sect2 id="path-disclosure-with-php-nuke"><title>Path disclosure with PHP-Nuke</title><para>Path disclosure is a vulnerability that enables a user to gain knowledge<indexterm><primary>knowledge</primary></indexterm> of the internal path structure of an installation.<indexterm><primary>installation</primary></indexterm> It affects not only PHP-Nuke, but almost all <acronym>PHP</acronym> scripts too. A typical path disclosure scenario goes as follows:</para><para>A user enters deliberately a value which is passed unchecked to the script. The value is crafted so as to cause an error in the <acronym>PHP</acronym> interpreter or the database server.<indexterm><primary>server</primary></indexterm> The user's speculation is that the error message will contain valuable information about the paths of the given software installation.<indexterm><primary>installation</primary></indexterm></para><para>As an example, the error could be something like:</para><screen><![CDATA[Fatal error: Cannot redeclare theindex() in
]]><![CDATA[/mnt/be1/02/738/0004711/w3/htdocs/www.yoursite.net/index.php
]]><![CDATA[on line 7
]]></screen><para>Typically, error reporting is set to display the errors on the served page and the user would gain knowledge of the full path of the index.<indexterm><primary>index</primary></indexterm>php script on the server.<indexterm><primary>server</primary></indexterm> This may or may not worry you, but it is a good idea to keep undisclosed<indexterm><primary>undisclosed</primary></indexterm> to malicious users. To achieve this, once a script is in production and displayed messages are no longer needed for debugging,<indexterm><primary>debugging</primary></indexterm> they should be disabled.</para><para>Path disclosure with <application>PHP-Nuke</application> has been reported in the following cases:</para><itemizedlist><listitem><para>The search module can't handle certain characters such as &quot;&quot;&quot;, &quot;&amp;gt;&quot; and &quot;'&quot;. This causes <application>PHP-Nuke</application> to return an error m essage that discloses the installation path (see <ulink url="http://www.secunia.com/advisories/10040/">PHP-Nuke Path Disclosure Vulnerability</ulink>).</para></listitem><listitem><para>The <acronym>PHP</acronym> script &quot;print.php&quot; used by the modules &quot;News&quot; and &quot;AvantGo&quot; does not verify user input supplied to the &quot;$sid&quot; variable. A malicious person could exploit this to gain knowledge of the full path to the installation directory by sending a HTTP request including invalid input to the &quot;$sid&quot; variable (see <ulink url="http://www.secunia.com/advisories/8321/">PHP-Nuke Path Disclosure</ulink>).</para></listitem></itemizedlist></sect2>
<sect2 id="cross-site-tracing-with-php-nuke"><title>Cross-site tracing with PHP-Nuke</title><para>A new vulnerability has been found in Microsoft's Internet Information Server (IIS) which allows the reading of cookies.<indexterm><primary>cookies</primary></indexterm> This is potentially possible also on Apache.<indexterm><primary>Apache</primary></indexterm> Since <application>PHP-Nuke</application> relies on the cookie mechanism (<xref linkend="cookies">) for user authentication,<indexterm><primary>authentication</primary></indexterm> it is important to know the risks emanating from this type of vulnerability.<indexterm><primary>vulnerability</primary></indexterm> Here is the way it works, according a <ulink url="http://www.cert.org/nav/index_main.html">CERT</ulink> advisory (see <ulink url="http://www.kb.cert.org/vuls/id/288308">Microsoft Internet Information Server (IIS) vulnerable to cross-site scripting via HTTP TRACK method</ulink>):</para><para>Microsoft IIS servers support the HTTP TRACK method. The HTTP TRACK method asks a web server to echo the contents of the request back to the client for debugging purposes. The TRACK request is not RFC compliant and not well documented.</para><para>The complete request, including HTTP headers,<indexterm><primary>headers</primary></indexterm> is returned in the entity-body of a TRACK response.<indexterm><primary>response</primary></indexterm> This leads to a Cross-site Scripting attack.<indexterm><primary>attack</primary></indexterm> Using features that provide client-side HTTP protocol support, such as <ulink url="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/xmlsdk/htm/xml_obj_ixmlhttprequest_8bp0.asp">XMLHTTP</ulink> ActiveX or XMLDOM scripting objects,<indexterm><primary>objects</primary></indexterm> a web site can cause browsers to issue TRACK requests. The site can read the TRACK response, including sensitive header information<indexterm><primary>information</primary></indexterm> such as cookies or authentication data.<indexterm><primary>data</primary></indexterm></para><para>Because the TRACK method is similar to the TRACE method, when combined with cross-domain browser vulnerabilities (<ulink url="http://www.kb.cert.org/vuls/id/244729">VU#244729</ulink>, <ulink url="http://www.kb.cert.org/vuls/id/711843">VU#711843</ulink>, <ulink url="http://www.kb.cert.org/vuls/id/728563">VU#728563</ulink>), HTTP TRACK and client-side HTTP support can be leveraged by attackers<indexterm><primary>attackers</primary></indexterm> to read sensitive header information from third-party domains.<indexterm><primary>domains</primary></indexterm> This technique has been termed &quot;Cross-Site Tracing,&quot; or XST,<indexterm><primary>XST</primary></indexterm> in <ulink url="http://www.cgisecurity.com/whitehat-mirror/WhitePaper_screen.pdf">Cross-Site Tracing (XST)</ulink>, a report published by WhiteHat Security. Cross-site tracing is also described in a <ulink url="http://www.kb.cert.org/vuls/id/867593">CERT advisory about Cross-Site-Tracing</ulink>.</para><para>As noted in the report of WhiteHat,<indexterm><primary>WhiteHat</primary></indexterm> the technique can be used to bypass the <ulink url="http://msdn.microsoft.com/workshop/author/dhtml/httponly_cookies.asp">HttpOnly</ulink> cookie attribute introduced in Microsoft Internet Explorer 6.0 SP1. HttpOnly blocks script access to the <ulink url="http://msdn.microsoft.com/workshop/author/dhtml/reference/properties/cookie.asp">cookie</ulink> property (document.cookie), but does not prevent a scripting object from reading the cookie out of an HTTP TRACK response.<indexterm><primary>response</primary></indexterm> In the White Paper of WhiteHat Security, this new method of Cross-Site-Scripting is explained in detail. The essence is that this technique</para><blockquote><para>...is able not only to bypass the httpOnly mechanism present in i.e. 6 service pack 1, but in addition the ability to xss just about anything from just about anywhere. This technique allows client-side scripting languages, such as javascript,<indexterm><primary>javascript</primary></indexterm> and possibly other client-side technologies like vbscript, flash,<indexterm><primary>flash</primary></indexterm> java, etc., the ability access http web authentication credentials,<indexterm><primary>credentials</primary></indexterm> with the added bonus of achieving this result over ssl.</para></blockquote><para>Normally, the cookie is sent back to the domain it belongs. But with this TRACE or TRACK HTTP method, it is possible to request a trace and the web server will send back all data,<indexterm><primary>data</primary></indexterm> <emphasis>including the cookie!</emphasis> This is especially important for PHP-Nuke, since it relies on cookies for the authentication of its users.</para><para>To protect yourself, you should deactivate the TRACE HTTP method , if you are using Apache, and the TRACK HTTP method, if you are using IIS:<indexterm><primary>IIS</primary></indexterm></para><itemizedlist><listitem><para>For Apache,<indexterm><primary>Apache</primary></indexterm> you should put the following in the .htaccess file (<xref linkend="htaccess-file">) of your document root (or, for performance reasons, directly in the configuration file of Apache,<indexterm><primary>Apache</primary></indexterm> if you have access to it):</para><screen><![CDATA[RewriteEngine On
]]><![CDATA[RewriteCond %{REQUEST_METHOD} ^TRACE
]]><![CDATA[RewriteRule .* - [F]
]]></screen><para>Of course, this assumes that you have mod_rewrite (<xref linkend="mod-rewrite">) installed.</para></listitem><listitem><para>For IIS,<indexterm><primary>IIS</primary></indexterm> you should filter out the TRACE and TRACK methods with the URLScan filter.<indexterm><primary>filter</primary></indexterm> The only methods allowed should be GET, HEAD and POST.<indexterm><primary>POST</primary></indexterm></para></listitem></itemizedlist><para>There is nothing you can do in the code of <application>PHP-Nuke</application> to avoid this vulnerability,<indexterm><primary>vulnerability</primary></indexterm> however you should bear in mind when we talk about cookies <xref linkend="cookies"> that a Cross-Site Tracing attack may steal the cookies of your <application>PHP-Nuke</application> too. See also <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=341">Cross-site tracing attack via HTTP TRACK / TRACE method</ulink>.</para></sect2>
</sect1>
<sect1 id="guard-security-vulnerabilities-in-php-nuke"><title>How to guard against security vulnerabilities in PHP-Nuke</title><para>After all the detailed excusion to the security risks lurking around your pristine installation of <application>PHP-Nuke</application> that was undertaken in the previous sections, you may be asking yourself if there is anything you can do to avoid them. Indeed, following the advice in this section, will render your <application>PHP-Nuke</application> system as secure as can be. </para><para>But there is also one point you should understand while talking about software (and especially Web software) security:<indexterm><primary>security</primary></indexterm> there is no absolute security! You can make life very difficult for the hypothetical &ldquo;malicious user&rdquo;, but then, given enough (time, money and criminal energy) resources,<indexterm><primary>sources</primary></indexterm> every system connected to the Web can become vulnerable. Thus, if your carreer depends on this, hire a security professional to check the code for you. </para><para>However, even if you are on your own, you can still do a lot to guard against security vulnerabilities.<indexterm><primary>vulnerabilities</primary></indexterm> You can:</para><itemizedlist><listitem><para>Stay current on developments and apply security fixes (see <xref linkend="security-fixes">).</para></listitem><listitem><para>Take the right security measures (see <xref linkend="security-measures">).</para></listitem><listitem><para>Perform a security audit of the code yourself (see <xref linkend="security-audit">).</para></listitem><listitem><para>Check file permissions (see <xref linkend="permissions2">) and cookie settings (see <xref linkend="cookies">).</para></listitem></itemizedlist><tip>
<title>
Disable HTML and uploads!
</title>
<para>
Many of the most important security risks arise from the fact that HTML is allowed in the News and Forums, or that users are allowed to upload avatars or mail attachments to the web server. You can thus diminish the attack potential against your site, if you disable HTML and uploads. But of course, this will not protect you from everything, so read on!
<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject>
</para>
</tip>
<sect2 id="security-fixes"><title>Security fixes</title><para>No piece of software is free from security related bugs.<indexterm><primary>bugs</primary></indexterm> <application>PHP-Nuke</application> is no exception to this rule. Due to its open source nature,<indexterm><primary>nature</primary></indexterm> everyone can search the source code for security holes. This is done by professionals and amateurs alike. When a security hole is found (i.e. a bug in the code that has the potential to enable unauthorized access<indexterm><primary>access</primary></indexterm> and/or execution of code, leading to a compromise of the system's integrity<indexterm><primary>integrity</primary></indexterm> or function), a bug fix will appear that closes it. It is of utmost importance to the integrity of your data to follow the developement in this area and apply those &ldquo;security fixes&rdquo; as soon as they become available.</para><para>If you run a fresh version of the analyze.<indexterm><primary>analyze</primary></indexterm>php script (see <xref linkend="analyze-php">), it will not only test your database connection and report errors, it will also warn you of any vulnerabilities regarding your <acronym>PHP</acronym> version (see <xref linkend="fig-analyze-warning-php">).
<figure id="fig-analyze-warning-php">
<title>
<acronym>PHP</acronym> security warning from analyze.php.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1174;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1174;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1174;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1174;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>PHP security warning from analyze.php.</phrase>
</textobject>
<caption>
<para>PHP security warning from analyze.php.</para>
</caption>
</mediaobject>
</figure>
</para><tip>
<title>
Run a fresh analyze.php regularly
</title>
<para>
analyze.php will also test other components of your system, such as MySQL, various modules etc. for known vulnerabilities, so you should run a fresh copy at regular intervalls (an old copy will not report new vulnerabilities, of course!). But it is also important that you do not rely completely on one script. There is no way around subscribing to the security mailing lists, if you want to stay current on developments in the software security field.
</para>
</tip>
<para>You should register yourself to well-known security advisories,<indexterm><primary>advisories</primary></indexterm> like those from <ulink url="http://www.secunia.com">secunia</ulink>, <ulink url="http://www.securityfocus.com">securityfocus</ulink>, <ulink url="http://www.cert.org">CERT</ulink>, <ulink url="http://neworder.box.sk">http://neworder.box.sk</ulink> or <ulink url="http://www.linuxsecurity.com">linuxsecurity</ulink> and filter those that are relevant to <acronym>PHP</acronym> and <application>PHP-Nuke</application> (unless you plan to read emails all day!). </para><para>Upon reading about a new vulnerability for PHP-Nuke, you should reach the pages of</para><itemizedlist><listitem><para><ulink url="http://phpnuke.org">PHP-Nuke</ulink></para></listitem><listitem><para><ulink url="http://www.nukecops.com">nukecops</ulink></para></listitem><listitem><para><ulink url="http://www.nukeresources.com">nukeresources</ulink></para></listitem><listitem><para><ulink url="http://www.nukesecurity.com">nukesecurity</ulink></para></listitem></itemizedlist><para>looking for available security fixes to apply. For example, <ulink url="http://www.nukeresources.com">nukeresources</ulink> collects all (security or not) fixes to the 6.x version of <application>PHP-Nuke</application> under <ulink url="http://www.nukeresources.com/downloads-cat-63.html">Downloads Category: PHPNuke 6.x / Fixes</ulink>.</para><para>If a new <acronym>PHP</acronym> vulnerability has been discovered, then the first place to run to, is <ulink url="http://www.php.net">php.net</ulink>.</para></sect2>
<sect2 id="security-measures"><title>Security measures </title><para>
<figure id="fig-analyze-warning-sitekey">
<title>
Site key security warning from analyze.php.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1175;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1175;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1175;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1175;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Site key security warning from analyze.php.</phrase>
</textobject>
<caption>
<para>Site key security warning from analyze.php.</para>
</caption>
</mediaobject>
</figure>
</para><para>Staying current on security fixes is only part of the story. The other part is a conservatively configured system.<indexterm><primary>system</primary></indexterm> Regarding security,<indexterm><primary>security</primary></indexterm> you cannot be overly conservative, so consider taking the following general security measures:</para><itemizedlist><listitem><para>Apply any security fixes available for your <application>PHP-Nuke</application> version (see <xref linkend="security-fixes">).</para></listitem><listitem><para>Do not allow HTML in the news,<indexterm><primary>news</primary></indexterm> forums, private messages or any other areas of <application>PHP-Nuke</application>. Use BBcode instead.</para></listitem><listitem><para>Do not allow uploading of images (e.g. for a gallery), avatars (e.g. for a forum) or mail attachments,<indexterm><primary>attachments</primary></indexterm> in any module, be it a forum, gallery, mail or whatever.</para></listitem><listitem><para>As long as the mailattach.php file is on the server,<indexterm><primary>server</primary></indexterm> even if the module is not active, you can get hacked.<indexterm><primary>hacked</primary></indexterm> Currently, the best fix is to delete the file (see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=15076">mailattach</ulink>). analyze.<indexterm><primary>analyze</primary></indexterm>php (see <xref linkend="analyze-php">) will issue a waring, if it finds the file in your installation (see <xref linkend="fig-analyze-warning-webmail">).</para></listitem><listitem><para>Delete the nuke.sql file from your web server,<indexterm><primary>server</primary></indexterm> as soon as you finished installation and everything is working correctly. First, you will not need it any more and second, if someone takes control<indexterm><primary>control</primary></indexterm> of your site, he could have the nice idea to rerun the nuke.sql file on your database,<indexterm><primary>base</primary></indexterm> thus bringing it to its original, pristine state (see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?p=55170">Hacked - now what?</ulink> for a real story).</para></listitem><listitem><para>You should also change your site key.<indexterm><primary>key</primary></indexterm> The best time to do this is during installation,<indexterm><primary>installation</primary></indexterm> while entering all the other parameters in config.php.<indexterm><primary>config.php</primary></indexterm> analyze.<indexterm><primary>analyze</primary></indexterm>php will issue a warning, if it finds the default site key in your config.<indexterm><primary>config</primary></indexterm>php (see <xref linkend="fig-analyze-warning-sitekey">). A site key is an important but often overlooked security feature of <application>PHP-Nuke</application>. It is used in generating security codes for authentication and resource access (e.g. downloads) purposes (see <ulink url="http://phpnuke.org/modules.php?name=News&amp;file=article&amp;sid=6555">PHP-Nuke Security GFX Mapping - Potential Risk</ulink> for details on how this is done). Each installation of <application>PHP-Nuke</application> system requires choosing a unique site key.<indexterm><primary>key</primary></indexterm> </para><para>You can use the <ulink url="http://mil-sim.net/modules.php?name=Downloads&amp;op=getit&amp;lid=21">Electric Dice</ulink> for this purpose. ElectricDice generates true random site keys that can be easily pasted into the config.<indexterm><primary>config</primary></indexterm>php file. As opposed to pseudo random numbers generated by computers,<indexterm><primary>computers</primary></indexterm> Electric Dice uses numbers generated from atmospheric noise in radio waves - a proven entropy source. ElectricDice is useful for both first time installation as well as updating your existing site key.<indexterm><primary>key</primary></indexterm>
</para></listitem></itemizedlist><para>
<figure id="fig-analyze-warning-webmail">
<title>
WebMail security warning from analyze.php.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1176;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1176;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1176;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1176;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>WebMail security warning from analyze.php.</phrase>
</textobject>
<caption>
<para>WebMail security warning from analyze.php.</para>
</caption>
</mediaobject>
</figure>
</para><para>To reduce the risk of SQL injection (see <xref linkend="SQL-injection-with-php-nuke">) and cross-site scripting (see <xref linkend="cross-site-scripting-with-php-nuke">), you can do the following:</para><itemizedlist><listitem><para>Set &ldquo;magic_quotes<indexterm><primary>magic_quotes</primary></indexterm>&rdquo; to ON in php.ini.<indexterm><primary>php.ini</primary></indexterm> When magic_quotes are on, all ' (single-quote), &quot; (double quote), \ (backslash) and NUL's are escaped with a backslash automatically, see <ulink url="http://www.php.net/ref.info">PHP Options and Information</ulink>.</para></listitem><listitem><para>Set &ldquo;register_globals<indexterm><primary>register_globals</primary></indexterm>&rdquo; to OFF in php.ini.<indexterm><primary>php.ini</primary></indexterm> When on, register_globals will inject (poison) your scripts will all sorts of variables, like request variables from html forms. This coupled with the fact that <acronym>PHP</acronym> doesn't require variable initialization<indexterm><primary>initialization</primary></indexterm> means writing insecure code is that much easier (see <ulink url="http://www.php.net/register_globals">Using Register Globals</ulink>).</para></listitem><listitem><para>Follow a well-thought user rights concept. Do not give users more rights to the database than it is absolutely necessary.</para></listitem></itemizedlist><note>
<title>
PHP-Nuke now works with register_globals set to OFF!
</title>
<para>
Contrary to the older 5.x versions that needed some extra script for this, newer versions (starting 6.0) of <application>PHP-Nuke</application> will work with register_globals set to OFF in the php.ini! Thus, there is no need to renounce this security measure, as far as <application>PHP-Nuke</application> is concerned. The reason is the following code that is now included in the start of mainfile.php:
</para>
<screen>
<![CDATA[if (!ini_get("register_globals")) {]]>
<![CDATA[ import_request_variables('GPC');]]>
<![CDATA[} ]]>
</screen>
<para>
Since every module includes mainfile.php, it also includes the above code, and will thus work with register_globals OFF. If, for some unusual reason, your module does not include mainfile.php, just add the above lines of code to make it work with register_globals OFF.
</para>
</note>
<para>To avoid path disclosure (see <xref linkend="path-disclosure-with-php-nuke">), you can:</para><itemizedlist><listitem><para>Set &quot;display_errors&quot;<indexterm><primary>display_errors</primary></indexterm> to off in php.ini or </para><screen><![CDATA[php_flag display_errors off
]]></screen><para>in .htaccess (see <xref linkend="htaccess-file">) or in an http configuration file.</para></listitem><listitem><para>Use PHP's error handling functions to disable error reporting or alter the handling (to email an admin for example, and display a less explicit error). </para></listitem></itemizedlist><tip>
<title>
Security Tip (from the <application>PHP-Nuke</application> INSTALL file)
</title>
<para>
It's a good choice to put your config.php file outside the Web Server path, then you can create a new config.php with the line: </para><screen><![CDATA[<?php include("../config.php"); ?> ]]></screen>
</tip>
<para>Some of the above measures may make <application>PHP-Nuke</application> less attractive to you, or your visitors, who would very much like, for example, to be able to write in HTML,<indexterm><primary>HTML</primary></indexterm> upload images at will, or attach nice files to their mails. It is up to you to weigh the risks and the merits of allowing or disabling a functionality.<indexterm><primary>functionality</primary></indexterm> A small, amateur site may take a different approach than a big, professional one. </para><para>And remember that the most secure website is one that is offline. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
</sect2>
<sect2 id="security-audit"><title>Security audit</title><para>Unfortunately, the above measures will not be enough to protect you, if the code is flawed. Thus, the most effective measure, is the one that needs a programmer and a security specialist together:</para><para>If you are a programmer,<indexterm><primary>programmer</primary></indexterm> or if you hire one: inspect (audit) the code and &ldquo;sanitize<indexterm><primary>sanitize</primary></indexterm>&rdquo; the data,<indexterm><primary>data</primary></indexterm> whenever it is input by the user. Sanitization is best achieved through a default-deny regular expression, like [^a-zA-Z0-9] - whatever matches the expression should be removed. The regular expression acts like a filter on user input. Make that filter as narrow as possible: if at all possible, allow only numbers, else letters and numbers. Make sure that any other characters, like symbols or punctuation,<indexterm><primary>punctuation</primary></indexterm> are converted to their HTML entity equivalents. Further, prefix and append a quote to all user input. For more programming tips, see <ulink url="http://www.nextgenss.com/papers/advanced_sql_injection.pdf">Advanced SQL Injection In SQL Server Applications</ulink> and <ulink url="http://www.spidynamics.com/whitepapers/WhitepaperSQLInjection.pdf">Web Applications and SQL Injection</ulink>.</para><para>If you rather prefer an explicit list of what to block,<indexterm><primary>block</primary></indexterm> try this one, taken from <ulink url="http://www.securiteam.com/securityreviews/5DP0N1P76E.html">SQL Injection Walkthrough</ulink>:</para><blockquote><para>Filter out characters like single quote, double quote, slash, backslash,<indexterm><primary>backslash</primary></indexterm> semicolon, extended characters like NULL,<indexterm><primary>NULL</primary></indexterm> carriage return, newline, etc, in all strings from:</para><itemizedlist><listitem><para>Input from users</para></listitem><listitem><para>Parameters from URLs</para></listitem><listitem><para>Values from cookies<indexterm><primary>cookies</primary></indexterm></para></listitem></itemizedlist><para>For a numeric value, convert it to an integer before parsing it into an SQL statement.</para></blockquote><para>Currently, <application>PHP-Nuke</application> checks with the following code for the presence of &ldquo;bad code&rdquo; in GET parameters:</para><screen><![CDATA[foreach ($_GET as $secvalue) {
]]><![CDATA[ if ((eregi("<[^>]*script*\"?[^>]*>", $secvalue)) ||
]]><![CDATA[ (eregi("<[^>]*object*\"?[^>]*>", $secvalue)) ||
]]><![CDATA[ (eregi("<[^>]*iframe*\"?[^>]*>", $secvalue)) ||
]]><![CDATA[ (eregi("<[^>]*applet*\"?[^>]*>", $secvalue)) ||
]]><![CDATA[ (eregi("<[^>]*meta*\"?[^>]*>", $secvalue)) ||
]]><![CDATA[ (eregi("<[^>]*style*\"?[^>]*>", $secvalue)) ||
]]><![CDATA[ (eregi("<[^>]*form*\"?[^>]*>", $secvalue)) ||
]]><![CDATA[ (eregi("<[^>]*img*\"?[^>]*>", $secvalue)) ||
]]><![CDATA[ (eregi("\([^>]*\"?[^)]*\)", $secvalue)) ||
]]><![CDATA[ (eregi("\"", $secvalue))) {
]]><![CDATA[ die ("I don't like you...");
]]><![CDATA[ }
]]><![CDATA[}
]]></screen><para>Notice that the expressions in the first argument of the eregi functions above are regular expressions (see <xref linkend="regular-expressions">). Their meaning is the following:</para><para>For the sake of example, we explain the first regular expression</para><screen><![CDATA[<[^>]*script*\"?[^>]*>
]]></screen><para>meaning &quot;anything that starts with &quot;&lt;&quot; (that's the first &quot;&lt;&quot; in the expression), immediately followed by zero or more occurrences (that's the &quot;*&quot; after the [^&gt;]) of a character that is NOT (that's the &quot;^&quot; inside the &quot;[^&gt;]&quot;) &quot;&gt;&quot; (that's what follows the &quot;^&quot; in the square brackets), immediately followed by &quot;script&quot;, followed by zero or more occurrences of &quot;t&quot; (that's the &quot;*&quot; after &quot;script&quot;, but it is wrong here, you probably should have a blank between &quot;script&quot; and &quot;*&quot;, meaning zero or more blanks....but let's continue ), immediately followed by zero or one &quot;&quot;&quot; (that's the &quot;&quot;?&quot; - don't let the double quotes mislead you, what we mean is &quot;zero or one double quote&quot; ), immediately followed by zero or more occurrences of any character that is not &quot;&gt;&quot; (that's the &quot;[^&gt;]*&quot; again...)&quot;. Phew...</para><para>As it stands, an expression like that will match everything that contains &ldquo;&lt; scriptxxxxxxxxx&rdquo;, where the x's stay for &ldquo;whatever&rdquo;. This may be too restrictive for you, as you might want to allow words that contain &ldquo;script&rdquo; as part of the word, but not the word &ldquo;script&rdquo; itself. Try the following regular expression instead:</para><screen><![CDATA[<[^>]*script +\"?[^>]*>
]]></screen><para>Uhmm...what's the difference? We have inserted a blank between &quot;script&quot; and the &quot;*&quot; immediately following it and have replaced the &quot;*&quot; with the &quot;+&quot;. Thus, the &quot;+&quot; will refer to the preceding blank (meaning &quot;one or more blanks&quot;, not &quot;zero or more t's&quot;, as in the case of the original &quot;script*&quot;). Remember, the &quot;*&quot; and the &quot;+&quot; and the &quot;?&quot; all refer to the <emphasis>preceding</emphasis> &quot;atom&quot; - it is NOT like &quot;dir *.exe&quot; here!</para><para>Small, but crucial! <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_cool.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_cool.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_cool.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_cool.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject></para>
<para>Further, go to modules/Forums/admin/common.php and have a look at the start of the code. There you can see how to use <ulink url="http://www.php.net/manual/en/function.addslashes.php">addslashes</ulink> to &quot;escape&quot; potentially dangerous characters (like quotes). Since we are dealing only with GET parameters in this discussion, you need only the part that is relevant to the $HTTP_GET_VARS array:</para><screen><![CDATA[//
]]><![CDATA[// addslashes to vars if magic_quotes_gpc is off
]]><![CDATA[// this is a security precaution to prevent someone
]]><![CDATA[// trying to break out of a SQL statement.
]]><![CDATA[//
]]><![CDATA[if( !get_magic_quotes_gpc() )
]]><![CDATA[{
]]><![CDATA[ if( is_array($HTTP_GET_VARS) )
]]><![CDATA[ {
]]><![CDATA[ while( list($k, $v) = each($HTTP_GET_VARS) )
]]><![CDATA[ {
]]><![CDATA[ if( is_array($HTTP_GET_VARS[$k]) )
]]><![CDATA[ {
]]><![CDATA[ while( list($k2, $v2) = each($HTTP_GET_VARS[$k]) )
]]><![CDATA[ {
]]><![CDATA[ $HTTP_GET_VARS[$k][$k2] = addslashes($v2);
]]><![CDATA[ }
]]><![CDATA[ @reset($HTTP_GET_VARS[$k]);
]]><![CDATA[ }
]]><![CDATA[ else
]]><![CDATA[ {
]]><![CDATA[ $HTTP_GET_VARS[$k] = addslashes($v);
]]><![CDATA[ }
]]><![CDATA[ }
]]><![CDATA[ @reset($HTTP_GET_VARS);
]]><![CDATA[ }
]]><![CDATA[}
]]><![CDATA[
]]></screen><para><ulink url="http://www.nukeresources.com">Chatserv</ulink> has recently undergone <application>PHP-Nuke</application> a detailed scrutiny from the security point of view and came up with <ulink url="http://www.nukeresources.com/article492.html">security patches for all 6.x and 7.x versions of PHP-Nuke</ulink> that cover:</para><itemizedlist><listitem><para>New Abstraction layer conversion.</para></listitem><listitem><para>Variables quoted on all sql queries.<indexterm><primary>queries</primary></indexterm></para></listitem><listitem><para>Security check added to most variables.</para></listitem><listitem><para>Bugs in core files fixed.</para></listitem><listitem><para>Previous sec-fix patches applied.</para></listitem></itemizedlist><para>You should include Chatserv's patches in your security audit and try to stay current on the developments in this area as much as you can. </para></sect2>
<sect2 id="permissions2"><title>Permissions on folders and files</title><para>This section is of importance only to those who use <application>PHP-Nuke</application> under Linux/Unix<indexterm><primary>Unix</primary></indexterm> (this is true for the greater part of <application>PHP-Nuke</application> sites that are hosted by providers, and often also those who test locally use Linux).</para><para>You have already set the right permissions on folders and files during installation (see <xref linkend="permissions">, where you will find a more in-depth treatment of the concept of file permissions). However, it is a good idea to think about permissions once again, in a security context.<indexterm><primary>context</primary></indexterm></para><para>Burzi says that the directories should be assigned a mode of 777,<indexterm><primary>777</primary></indexterm> the files a mode of 666,<indexterm><primary>666</primary></indexterm> but we may calmly let our <application>PHP-Nuke</application> do its work under more restrictive permissions,<indexterm><primary>permissions</primary></indexterm> as illustrated below:</para><itemizedlist><listitem><para>config.php (666)</para></listitem><listitem><para>backend.php (666)</para></listitem><listitem><para>ultramode.txt (666)</para></listitem><listitem><para>All directories (755)</para></listitem><listitem><para>Other files (644)</para></listitem></itemizedlist><para>The files config.php, backend.php, ultramode.txt must have the write permissions<indexterm><primary>permissions</primary></indexterm> because :</para><itemizedlist><listitem><para>For config.php editing the preferences we will write this file modifying the text.</para></listitem><listitem><para>For the backend and ultramode on the other side, we will write them (in an automatic way) modifying the titles and abstracts of the news.<indexterm><primary>news</primary></indexterm> </para></listitem></itemizedlist><para>There is however something particular we have to take into account: if we use modules that upload files in some directories, their permissions wil have to be raised. As an example, consider the IndyNews module,<indexterm><primary>module</primary></indexterm> a non standard module that makes it possible to enclose files and images in articles. The structure of the module is the following:</para><itemizedlist><listitem><para>modules/indynews/media</para></listitem></itemizedlist><para>In the inside of the &ldquo;indynews<indexterm><primary>indynews</primary></indexterm>&rdquo; folder the permissions of the folder &ldquo;media&rdquo; would have to be 777,<indexterm><primary>777</primary></indexterm> due to an override problem, the 777 permissions will have to be imposed on everything that is below &ldquo;modules<indexterm><primary>modules</primary></indexterm>&rdquo;. For this reason, everything that resides in &ldquo;modules<indexterm><primary>modules</primary></indexterm>&rdquo; will be in 777 mode and this could cause a vulnerability.<indexterm><primary>vulnerability</primary></indexterm> A solution is to move the folder that will have to accommodate the uploaded files to the outside of the modules folder, even to the document root,<indexterm><primary>root</primary></indexterm> changing inside the module all the references to it.</para><para>Doing so will leave one single folder in root with permissions set to 777.<indexterm><primary>777</primary></indexterm> But you still have to consider the risks associated with such a decision. To quote the <ulink url="http://free-source.com/files/phpgw-howto.html#2.3">phpGroupWare Installation and security HOWTO</ulink>:</para><blockquote><para>As discussed earlier, having a world writable file in you web root is a rather serious security risk,<indexterm><primary>risk</primary></indexterm> especially if that file will accept raw user data.<indexterm><primary>data</primary></indexterm> It becomes trivial for someone to add php code or any type of script or cgi code your server supports and execute it on your system.<indexterm><primary>system</primary></indexterm> Risk is reduced slightly because it would be executed as the &quot;anonymous&quot;<indexterm><primary>anonymous</primary></indexterm> nobody user that apache runs under but still would allow access to your ...[ed. config.php] and thus your database,<indexterm><primary>base</primary></indexterm> as well as access to /etc/* where all sorts of fun and dangerous information could be abused.<indexterm><primary>abused</primary></indexterm></para></blockquote><para>Thus, if the upload feature is of utmost importance to you, you are well advised to double-check what kinds of files your users will be allowed to upload - and test any paranoid scenario you can think of. In case of doudt, it may be safer to disable uploading at the cost of making some users unhappy. Better safe than sory.</para></sect2>
<sect2 id="cookies"><title>Cookies - timeout and configuration</title><para>PHP-Nuke makes heavy use of cookies,<indexterm><primary>cookies</primary></indexterm> be it for user authentication, or admin authentication.<indexterm><primary>authentication</primary></indexterm> The cookies are text files that are saved on our computers and contain various information that is read when we enter a certain site. In the case of <application>PHP-Nuke</application> the information saved there pertains to the user, the chosen theme and the language used. </para><para>The cookie is also the instrument that enables us not to have to retype the password each time we log in. This way, each time we access a <application>PHP-Nuke</application> site, the cookie works for us by managing the login operation.<indexterm><primary>operation</primary></indexterm></para><sect3 id="cookie-hijack"><title>Cookie hijack</title><para>The problem is that if the cookie does not have an expiry date low enough, someone can to steal it from us and be able to access the site as a user or administrator.<indexterm><primary>administrator</primary></indexterm> This is possible for a series of reasons:</para><orderedlist><listitem><para>The cookie of <application>PHP-Nuke</application> has a life duration close to infinite (31536000 seconds)</para></listitem><listitem><para>Explorer (most used browser, unfortunately) has vulnerabilities that allow the execution of malicious scripts on the client that &ldquo;steal&rdquo; the cookie from the user and send it to the &ldquo;burglar<indexterm><primary>burglar</primary></indexterm>&rdquo;.</para></listitem><listitem><para>PHP-Nuke does not succeed in filtering all the malicious scripts (or, to put it better, Internet Explorer is so stupid that corrects inserted scripts with the wrong syntax in order not to be recognized).</para></listitem></orderedlist><para>Let's show a concrete example of how a script kiddie (those who hold themselves for hackers, but they are not...) can try to obtain administrator rights on our site:</para><orderedlist><listitem><para>The script kiddie inserts a script that supposedly contains news:<indexterm><primary>news</primary></indexterm> </para><screen><![CDATA[< vb script give the cookie to me and send it to the server xyz>
]]></screen><para>that is not filtered by the function check_words() of <application>PHP-Nuke</application>.</para></listitem><listitem><para>The administrator of <application>PHP-Nuke</application> opens the page up with Internet Explorer!!! (This hack does not work if you're using Mozilla,<indexterm><primary>Mozilla</primary></indexterm> or better yet, any <productname>Linux</productname> browser). The list of the news waiting to be approved for publishing is seen by the administrator.<indexterm><primary>administrator</primary></indexterm> When he goes to look at the Submissions,<indexterm><primary>Submissions</primary></indexterm> Internet Explorer (stupidly) corrects the vbscript in this way: </para><screen><![CDATA[<vbscript>(script kiddies commands go here)
]]></screen><para>succeeding to interpret the wrong syntax in the correct way (!!!), taking the cookie and sending it to the script kiddie.<indexterm><primary>script kiddie</primary></indexterm></para></listitem><listitem><para>The script kiddie puts the cookie among the other ones of his own, connects to the site and... is recognized as being the administartor!!!</para></listitem></orderedlist><para>But how is it possible to protect ourselves from this type of hack?<indexterm><primary>hack</primary></indexterm></para><para>There are some solutions that should increase the security for our administration area:</para><orderedlist><listitem><para>First of all STOP using Internet Explorer as a browser and pass the seat to <ulink url="http://www.mozilla.org">Mozilla</ulink>. Mozilla is a browser that supports all sites in an optimal way and is not plagued by all the vulnerabilities of Microsoft.<indexterm><primary>Microsoft</primary></indexterm> If you use <productname>Linux</productname> instead you won't encounter any problems of this sort...</para><orderedlist><listitem><para><indexterm><primary>Enumerate</primary></indexterm>In case you want to continue to use the Explorer, you should at least download<indexterm><primary>download</primary></indexterm> the patches from <ulink url="http://www.microsoft.com">Microsoft</ulink>.</para></listitem></orderedlist></listitem><listitem><para>Disable, where possible, the insertion of HTML tags (for example in the forum)</para></listitem><listitem><para>Narrow down the life of cookies.<indexterm><primary>cookies</primary></indexterm> If for example we set up the life of the cookie to two hours,<indexterm><primary>hours</primary></indexterm> the script kiddie will be forced to use the cookie within that period, this limits much of their ability to act in time.</para><para>If instead we leave the life of the cookie to its preset value, the script kiddie may use our cookie even for 1 month after it was stolen.<indexterm><primary>stolen</primary></indexterm></para><para>How to set up the duration of the administartor cookie?<indexterm><primary>cookie</primary></indexterm> The cookie is set up in the file includes/auth.php and the function to modify it is the following:</para><screen><![CDATA[if ((isset($aid)) && (isset($pwd)) && ($op == "login")) {
]]><![CDATA[ if($aid! = "" AND $pwd!="") {
]]><![CDATA[ $pwd = md5($pwd);
]]><![CDATA[ $result=sql_query("select pwd, admlanguage from "$prefix."_authors where aid='$aid'", $dbi);
]]><![CDATA[ list($pass, $admlanguage)=sql_fetch_row($result, $dbi);
]]><![CDATA[ if($pass == $pwd) {
]]><![CDATA[ $admin = base64_encode("$aid:$pwd:$admlanguage");
]]><![CDATA[ setcookie("admin", "$admin",time()+7200);
]]><![CDATA[ unset($op);
]]><![CDATA[ }
]]><![CDATA[ }
]]><![CDATA[}
]]></screen><para>As you see we have modified the life duration of the second cookie from 2592000 (a month) to 7200 seconds (two hours). As you can easily see, we have reduced the action radius of the script kiddie down from one month to two hours.<indexterm><primary>hours</primary></indexterm></para></listitem><listitem><para>A much more effective tag filter is realized through the check_html and filter_text functions in mainfile.php (see <xref linkend="allow-special-HTML-tags">). The admissible tags are defined in the file config.php in the $AllowableHTML<indexterm><primary>AllowableHTML</primary></indexterm> array, these are valid for the comments,<indexterm><primary>comments</primary></indexterm> the insertion of news and many other user inputs (see <xref linkend="tab-filter-text"> and <xref linkend="tab-check-html"> for all instances of a call to the filter_text and check_html functions respectively).</para></listitem></orderedlist><para>All these actions and a correct configuration of the permissions as illustrated<indexterm><primary>illustrated</primary></indexterm> in <xref linkend="permissions"> and <xref linkend="permissions2">, should guarantee us a good security for our site. It is also important to closely follow the security warnings for <application>PHP-Nuke</application> that are brought up on the various security advisories (see <xref linkend="security-fixes">).</para></sect3>
<sect3 id="user-cookie-change-duration"><title>Changing the duration of the user cookie</title><para>If you want to redefine the duration of the <emphasis>user</emphasis> cookie (as opposed to the administrator cookie), you have to edit the file modules/Your_Account/index.php.<indexterm><primary>index.php</primary></indexterm> There, find the function docookie():</para><screen><![CDATA[function docookie($setuid, $setusername, $setpass, $setstorynum, $setumode,
]]><![CDATA[$setuorder, $setthold, $setnoscore, $setublockon, $settheme, $setcommentmax) {
]]><![CDATA[ $info = base64_encode("$setuid:$setusername:$setpass:$setstorynum:$setumode:
]]><![CDATA[$setuorder:$setthold:$setnoscore:$setublockon:$settheme:$setcommentmax");
]]><![CDATA[ setcookie("user","$info",time()+2592000);
]]><![CDATA[}
]]></screen><para>and change the 2592000 seconds (30 days) to the duration of your choice. </para><para>If you want the user cookie to expire as soon as the user closes his browser, to avoid problems with internet cafes and similar situations where a user might forget to log off your site and leave his browser still running, thus making it trivial for others to use his <application>PHP-Nuke</application> account, you should set a <emphasis>temporary</emphasis> cookie.<indexterm><primary>cookie</primary></indexterm> This is done by removing the time altogether:</para><screen><![CDATA[setcookie("user","$info");
]]></screen><para>See:</para><itemizedlist><listitem><para><ulink url="http://www.php.net/setcookie">PHP Manual on setcookie</ulink>,</para></listitem><listitem><para><ulink url="http://www.nukeforums.com/forums/viewtopic.php?topic=15342&amp;forum=26">user Log off</ulink>,</para></listitem><listitem><para><ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=14003">cookie expire time</ulink></para></listitem><listitem><para><ulink url="http://www.nukeforums.com/forums/viewtopic.php?p=57872">how to force all users to relogin</ulink> and </para></listitem><listitem><para><ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=78">automatic logout</ulink></para></listitem></itemizedlist><para>for discussions on this subject.</para></sect3>
</sect2>
</sect1>
<sect1 id="ban-IP-addresses"><title>How to ban IP addresses</title><para>So you have been hacked and your IP Tracking module (<xref linkend="PHP-Nuke-IP-Tracking-module">) shows you it was an attack from a few IP addresses? Perhaps your site is continuing to be the aim of notorious cracking attempts from those IP<indexterm><primary>IP</primary></indexterm> addresses and you now want to ban them? That's something you can accomplish easily in two ways, a hard-coded approach and a more elaborate one.</para><para>The hard-coded approach (suitable only for just a few IP addresses, unless you want to clutter the code with unwanted IPs) requires you to place this 4-liner:<indexterm><primary>4-liner</primary></indexterm></para><screen><![CDATA[$ip = getenv("REMOTE_ADDR");
]]><![CDATA[if ($ip != "66.666.66.6" AND $ip != "55.555.55.5") {
]]><![CDATA[return 0;
]]><![CDATA[}
]]></screen><para>in two places:</para><orderedlist><listitem><para>after the global line of the is_amdin() function in mainfile.php and</para></listitem><listitem><para>at the begining of the admin.<indexterm><primary>admin</primary></indexterm>php file.</para></listitem></orderedlist><para>Change the &ldquo;66.666.<indexterm><primary>666</primary></indexterm>66.6&rdquo; and &ldquo;55.555.55.5<indexterm><primary>55.555.55.5</primary></indexterm>&rdquo; to the IP addresses you want to block and you are done! See <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=13987">How to block an IP address in PHP-Nuke</ulink>.</para><para>The more elaborate approach is to create a text file, call it banned.<indexterm><primary>banned</primary></indexterm>txt, containing all the IP addresses you want to ban,<indexterm><primary>ban</primary></indexterm> one address per line. Upload banned.<indexterm><primary>banned</primary></indexterm>txt in the <application>PHP-Nuke</application> root directory on your web server (this is the same directory where also config.<indexterm><primary>config</primary></indexterm>php is located). Then include the following code in the includes/my_header.<indexterm><primary>header</primary></indexterm>php file (the custom HTML header file of PHP-Nuke, see <xref linkend="modifying-php-nuke-html-header">):</para><screen><![CDATA[if (isset($_SERVER['HTTP_X_FORWARDED_FOR'])) {
]]><![CDATA[ $ip = $_SERVER['HTTP_X_FORWARDED_FOR'];
]]><![CDATA[}
]]><![CDATA[elseif (isset($_SERVER['HTTP_VIA'])) {
]]><![CDATA[ $ip = $_SERVER['HTTP_VIA'];
]]><![CDATA[}
]]><![CDATA[elseif (isset($_SERVER['REMOTE_ADDR'])) {
]]><![CDATA[ $ip = $_SERVER['REMOTE_ADDR'];
]]><![CDATA[}
]]><![CDATA[else {
]]><![CDATA[ $ip = "Banned";
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[$banned = file("banned.txt", "r+");
]]><![CDATA[$nbanned = count($banned);
]]><![CDATA[
]]><![CDATA[function ban($ip, $banned, $nbanned){
]]><![CDATA[ for ($i = 0 ; $i < $nbanned ; $i++) {
]]><![CDATA[
]]><![CDATA[ // Use this if you want to use IP patterns with regular expressions:
]]><![CDATA[ // if (eregi($ip, $banned[$i])) {
]]><![CDATA[
]]><![CDATA[ // We have to strip the end-of-line characters, to test for equality:
]]><![CDATA[ if ($ip == rtrim($banned[$i])) {
]]><![CDATA[ echo "You have been banned from this portal, if you feel this is in error ";
]]><![CDATA[ echo "please send email to you@yoursite.com ";
]]><![CDATA[ die();
]]><![CDATA[ }
]]><![CDATA[ }
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[ban($ip, $banned, $nbanned);
]]></screen><para>If you are having problems with <acronym>PHP</acronym> not recognizing the line endings when reading files with the <ulink url="http://www.php.net/manual/en/function.file.php">PHP file() function</ulink> (see the code above), either on or created by a Macintosh computer, you might want to enable the <ulink url="http://www.php.net/manual/en/ref.filesystem.php#ini.auto-detect-line-endings">auto_detect_line_endings</ulink> run-time configuration option (which, however, is available only starting <acronym>PHP</acronym> v. 4.3.0).</para><para>If you would like to ban whole ranges of IP addresses, you can play with the <ulink url="http://www.php.net/manual/en/function.eregi.php">PHP eregi() function</ulink> and use </para><screen><![CDATA[if (eregi($ip, $banned[$i])) {
]]></screen><para>instead of</para><screen><![CDATA[if ($ip == rtrim($banned[$i])) {
]]></screen><para>You then use patterns of IP addresses, i.e. regular expressions (see <xref linkend="regular-expressions">, <ulink url="http://www.php.net/regex">Regular Expression Functions (POSIX Extended)</ulink>), instead of constant IPs in banned.<indexterm><primary>banned</primary></indexterm>txt. See also <ulink url="http://www.grancanariayoungsters.com/ftopicp-322.html">How to ban IPs real fast</ulink>.</para><tip>
<title>
How to ban IPs using the web server
</title>
<para>
Of course, you can achieve the same results by putting deny directives in the server configuration file, or .htaccess file (<xref linkend="htaccess-file">):
</para>
<screen>
<![CDATA[deny from xxx.xxx.xxx.xxx]]>
</screen>
</tip>
<para>See the Protector Module (<xref linkend="PHP-Nuke-Protector-module">) for a <application>PHP-Nuke</application> module for IP banning.<indexterm><primary>banning</primary></indexterm></para></sect1>
<sect1 id="hacked-now-what"><title>Hacked - now what?</title><para>Here is an incomplete list of what you can do when you realize that your <application>PHP-Nuke</application> site has been hacked:<indexterm><primary>hacked</primary></indexterm></para><itemizedlist><listitem><para>Check the files on your server against your latest backup to check for any modifications.<indexterm><primary>modifications</primary></indexterm><ulink url="http://www.tripwire.org">Tripwire</ulink> can help you with this task.</para></listitem><listitem><para>Reset all admin passwords.<indexterm><primary>words</primary></indexterm></para></listitem><listitem><para>Search the logs for the message posting URL,<indexterm><primary>URL</primary></indexterm> e.g. *admin.php?<indexterm><primary>admin.php</primary></indexterm>op=messages , find the perpetrator's IP and notify the person responsible for the network.</para></listitem><listitem><para>If using Apache, create &quot;admin&quot;<indexterm><primary>admin</primary></indexterm> user group, add a new user to this group and create the appropriate .htaccess file (<xref linkend="htaccess-file">).</para></listitem><listitem><para>Limit access to admin.<indexterm><primary>admin</primary></indexterm>php to a &quot;tight&quot; IP range/subnet.</para></listitem><listitem><para>Install the Protector module (<xref linkend="PHP-Nuke-Protector-module">), which gives you &quot;high level&quot; logs of session activity on your <application>PHP-Nuke</application> site.</para></listitem><listitem><para>Re-evaluate the security of installed 3rd party modules/blocks.</para></listitem></itemizedlist><para>See also </para><itemizedlist><listitem><para><ulink url="http://www.nukecops.com/postitle17223-0-0-.html">My site running phpnuke 6.9 got hacked</ulink>, </para></listitem><listitem><para><ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=14487">Hacked - what do I do?</ulink>,</para></listitem><listitem><para><ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=17131">My site has reset itself to the 'welcome to php-nuke' screen</ulink>.</para></listitem></itemizedlist></sect1>
</chapter>
<chapter id="accelerating-php-nuke"><title>Accelerating PHP-Nuke</title><para>
<figure id="fig-optimize-2">
<title>
Accelerating <application>PHP-Nuke</application>.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1177;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1177;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1177;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1177;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Accelerating <application>PHP-Nuke</application>.</phrase>
</textobject>
<caption>
<para>Accelerating <application>PHP-Nuke</application>.</para>
</caption>
</mediaobject>
</figure>
</para><para>Want a lightning fast PHP-Nuke? Read on... <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
<variablelist><varlistentry><term>Problem:
</term><listitem><para>You installed all kinds of modules,<indexterm><primary>modules</primary></indexterm> blocks and image galleries on your <application>PHP-Nuke</application>. Now, you notice that it has become painfully slow. What can be done to accelarate things a bit?</para></listitem></varlistentry><varlistentry><term>Idea:
</term><listitem><para><ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=130">Cache PHP-Nuke</ulink>!</para></listitem></varlistentry></variablelist><sect1 id="caching-php-nuke"><title>Caching PHP-Nuke</title><para>As in <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=130">How to accelerate PHP-Nuke</ulink>, we ask ourselves the following questions:</para><itemizedlist><listitem><para>Does your index.php,<indexterm><primary>index.php</primary></indexterm> or the other parts of your <application>PHP-Nuke</application> change more often than, say, once in 15 minutes? Maybe not, if you are not logged in.</para></listitem><listitem><para>Do you really need to see a change the very moment you hit the reload button of your browser? For me, if this change is the number of private messages I got, then I might be interested to see the *real* number. But then again, why not the number as of 5 minutes ago? How important is current content for you? How current is current enough for you? 1 minute, 5 minutes, or even 15 minutes? </para></listitem></itemizedlist><para>If you think a little about it, you will realize that maybe it is not absolutely necessary that your <application>PHP-Nuke</application> does all these conections to the database,<indexterm><primary>base</primary></indexterm> querying all that data that most probably did not change the last x minutes, each time you display a page.</para><para>
<figure id="fig-optimize-php">
<title>
Optimizing <acronym>PHP</acronym> code execution.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1178;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1178;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1178;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1178;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Optimizing <acronym>PHP</acronym> code execution.</phrase>
</textobject>
<caption>
<para>Optimizing <acronym>PHP</acronym> code execution.</para>
</caption>
</mediaobject>
</figure>
</para><para>Various tests on optimizing <acronym>PHP</acronym> (see, for example, <ulink url="http://phplens.com/lens/php-book/optimizing-debugging-php.php">Optimizing PHP</ulink>) have shown that the biggest time savings in execution time are not achieved through elaborate algorithmic optimization,<indexterm><primary>optimization</primary></indexterm> but rather with an old, well-known technique: caching! The idea behind caching is to avoid repeated execution of the <acronym>PHP</acronym> code, by storing the HTML output in a file, as jpcache (<xref linkend="jpcache">) and Cache-Lite (<xref linkend="cache-lite">) do, or in shared memory,<indexterm><primary>memory</primary></indexterm> as Turck MMCache (<xref linkend="Turck-MMCache">) does. Optimizers,<indexterm><primary>Optimizers</primary></indexterm> such as the commercial <ulink url="http://www.zend.com">Zend Performance Suite</ulink> and the free Turck MMCache,<indexterm><primary>MMCache</primary></indexterm> transform the <acronym>PHP</acronym> code in an intermediate form, an &ldquo;opcode&rdquo; , which they cache - <xref linkend="fig-optimize-php"> shows the way these optimizers work. In the following we will examine them in more detail.</para><caution>
<title>Know what you cache and why!</title>
<para>
If you try to cache the whole index.php page even for registered users, you shouldn't be surprised of the errors and you shouldn't blame it on cache. The cache will just cache what you tell it to, for the time intervall you tell it to.
</para>
<para>
Now, suppose that your users get different output on your index.php page, depending on your settings as an administrator (blocks, modules etc.) and their settings as users. Also suppose that you use a caching mechanism, like the ones we will describe later in this chapter, to cache the whole index.php page. Then we can easily imagine a situation where your user A will not get to see what he should see, but what user B was viewing a few minutes ago. In other words, all users will see user's B cached index.php page, with all the wrong links in it, like "Your Account" with user's B data in the link etc.
</para>
<para>
For this reason, it is absolutely necessary to know what you cache and why you cache it!
</para>
</caution>
<tip>
<title>What to cache for registered users</title>
<para>
If you want to cache content when it is viewed by registered users too, it will make more sense to cache only individual modules or blocks which (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?p=2006">Caching strategy with PHP-Nuke</ulink>)
</para>
<itemizedlist>
<listitem>
<para>
take much time to build their content and
</para>
</listitem>
<listitem>
<para>
their content is independent of the user viewing it.
</para>
</listitem>
</itemizedlist>
</tip>
<sect2 id="jpcache"><title>jpcache</title><para>
<figure id="fig-jpcache">
<title>
Powered by jpcache.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1179;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1179;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1179;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1179;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Powered by jpcache.</phrase>
</textobject>
<caption>
<para>Powered by jpcache.</para>
</caption>
</mediaobject>
</figure>
</para><para>Enter <ulink url="http://www.jpcache.com">jpcache</ulink>: jpcache is a lightweight,<indexterm><primary>lightweight</primary></indexterm> full page caching system for PHP, thus reducing server load,<indexterm><primary>load</primary></indexterm> as pages are generated less often. It dramatically speeds up serving of your pages, by caching page ouput and returning the chached page instead of compiling the <acronym>PHP</acronym> one. In the following we will describe jpcache installation,<indexterm><primary>installation</primary></indexterm> configuration and use (see also <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=130">How to accelerate PHP-Nuke</ulink>):</para><sect3 id="jpcache-installation"><title>Installation of jpcache</title><para>Installation is very simple:</para><itemizedlist><listitem><para>Download it from the <ulink url="http://sourceforge.net/project/showfiles.php?group_id=23902&amp;release_id=173955">jpcache download page at sourceforge.net</ulink>.</para></listitem><listitem><para>Extract the files in the includes directory of your <application>PHP-Nuke</application>. A folder &quot;jpcache&quot;<indexterm><primary>jpcache</primary></indexterm> will be created containing all the necessary files. Change to that folder.</para></listitem><listitem><para>Read the readme file.</para></listitem></itemizedlist></sect3>
<sect3 id="jpcache-configuration"><title>Configuration of jpcache</title><itemizedlist><listitem><para>Edit the $includedir variable in the jpcache.<indexterm><primary>jpcache</primary></indexterm>php file to reflect the *full* path to the jpcache files:</para><screen><![CDATA[// Set the includedir to the jpcache-directory
]]><![CDATA[$includedir = "/usr/local/httpd/htdocs/nuke6/html/includes/jpcache";
]]></screen></listitem><listitem><para>Edit the jpcache-config.<indexterm><primary>config</primary></indexterm>php file. You basically only need to set the $JPCACHE_TYPE to &quot;file&quot; (remember, we want to avoid database connections):</para><screen><![CDATA[$JPCACHE_TYPE = "file";
]]><![CDATA[//$JPCACHE_TYPE = "mysql";
]]><![CDATA[//$JPCACHE_TYPE = "dbm"; -- Not yet
]]></screen><para>then coment the next block (you don't need it, since you *did* specified the $JPCACHE_TYPE above):</para><screen><![CDATA[// DOH! Strip out this check for performance if you are sure you did set it.
]]><![CDATA[// if (!isset($JPCACHE_TYPE))
]]><![CDATA[// {
]]><![CDATA[// exit("[jpcache-config.php] No JPCACHE_TYPE has been set!");
]]><![CDATA[// }
]]></screen><para>Just check the configuration options to see what they do, the defaults are O.K. for me:</para><screen><![CDATA[/**
]]><![CDATA[* General configuration options.
]]><![CDATA[*/
]]><![CDATA[$JPCACHE_TIME = 900; // Default number of seconds to cache a page
]]><![CDATA[$JPCACHE_DEBUG = 0; // Turn debugging on/off
]]><![CDATA[$JPCACHE_IGNORE_DOMAIN= 1; // Ignore domain name in request(single site)
]]><![CDATA[$JPCACHE_ON = 1; // Turn caching on/off
]]><![CDATA[$JPCACHE_USE_GZIP = 1; // Whether or not to use GZIP
]]><![CDATA[$JPCACHE_POST = 0; // Should POST's be cached (default OFF)
]]><![CDATA[$JPCACHE_GC = 1; // Probability % of garbage collection
]]><![CDATA[$JPCACHE_GZIP_LEVEL = 9; // GZIPcompressionlevel to use (1=low,9=high)
]]><![CDATA[$JPCACHE_CLEANKEYS = 0; // Set to 1 to avoid hashing storage-key:
]]><![CDATA[// you can easily see cachefile-origin.
]]></screen></listitem><listitem><para>Finally, set the directory for the cached files, preferably outside your web server root, say /tmp/jpcache.<indexterm><primary>jpcache</primary></indexterm> Create it, set the owner and group equal to the owner and group of your web server and change the permissions to 755 (rwx-r-x-r-x), or even 750<indexterm><primary>750</primary></indexterm> (rwx-r-x----). Then, enter in jpcache-config.<indexterm><primary>config</primary></indexterm>php the absolute path to that cache directory:</para><screen><![CDATA[/**
]]><![CDATA[* File based caching setting.
]]><![CDATA[*/
]]><![CDATA[$JPCACHE_DIR = "/tmp/jpcache"; // Directory where jpcache must store
]]><![CDATA[// generated files. Please use a dedicated
]]><![CDATA[// directory, and make it writable
]]></screen></listitem></itemizedlist><para>That's all! jpcache is now configured correctly. </para></sect3>
<sect3 id="jpcache-use"><title>How to use jpcache</title><para>To use it, just open the index.<indexterm><primary>index</primary></indexterm>php file of your <application>PHP-Nuke</application> and enter the following lines, after the line &quot;require_once(&quot;mainfile.php&quot;<indexterm><primary>mainfile.php</primary></indexterm>);&quot; (that's important!):</para><screen><![CDATA[require_once("mainfile.php");
]]><![CDATA[
]]><![CDATA[if (!isset($user)) {
]]><![CDATA[ $cachetimeout=900;
]]><![CDATA[} else {
]]><![CDATA[ $cachetimeout=300;
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[require_once "includes/jpcache/jpcache.php";
]]></screen><para>(I have included the 'require_once(&quot;mainfile.php&quot;<indexterm><primary>mainfile.php</primary></indexterm>);' line in the code above for your orientation).</para><para>That's it! You can now tweak the two caching intervalls, 900 and 300 seconds, which apply to non-logged-in and logged-in users respectively. Rethink the questions I asked you in <xref linkend="caching-php-nuke"> above. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject></para>
<para>A caching intervall of x seconds means that your server will serve you a cached copy of the page, if the cache copy is not older than x seconds.<indexterm><primary>seconds</primary></indexterm> Since non-logged-in users don't get private messages or similar &quot;events&quot;, a longer caching intervall is just right for them. Feel free to experiment with these two values, trading actuality of content against serving speed.<indexterm><primary>speed</primary></indexterm></para><para>Enjoy your new, lightning fast PHP-Nuke!</para><para>Oops...I forgot a crucial detail:</para><para>You must edit the mainfile.php file too! There, you *must* comment the line</para><screen><![CDATA[ob_start("ob_gzhandler");
]]></screen><para>as follows:</para><screen><![CDATA[# ob_start("ob_gzhandler");
]]></screen><para>Otherwise, you will be compressing twofold, once from <application>PHP-Nuke</application> with the above line and once with jpcache through the configuration line</para><screen><![CDATA[$JPCACHE_USE_GZIP = 1; // Whether or not to use GZIP
]]></screen><para>of jpcache-config.php.<indexterm><primary>jpcache-config.php</primary></indexterm></para><para>The other way round, turning off gzip in jpcache and leaving the ob_start(&quot;ob_gzhandler&quot;) line uncommented in PHP-Nuke, works too. It may even be better to choose this way, if you use Apache and mod_gzip<indexterm><primary>mod_gzip</primary></indexterm> (a common configuration).</para><tip>
<title>
How to test if caching is working
</title>
<para>
You can check if you are doing it right, by trying to cache a block that just echoes the current time. If the cached block displays the same time again and again after reloading (for some time interval equal to the "cache interval"), then caching is working!
</para>
<para>
If it displays the current time (which is changing after every reloading), then caching is NOT working! In this case, most probably no files are being written into the cache directory you specified. Most of the time, this will be a permissions problem: check that the web server has write and execute permissions on the cache directory! See <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=130">How to accelerate PHP-Nuke</ulink>.
</para>
</tip>
</sect3>
</sect2>
<sect2 id="cache-lite"><title>Cache-Lite</title><para>
<figure id="fig-pear">
<title>
Cache-Lite is powered by PEAR.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1180;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1180;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1180;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1180;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Cache-Lite is powered by PEAR.</phrase>
</textobject>
<caption>
<para>Cache-Lite is powered by PEAR.</para>
</caption>
</mediaobject>
</figure>
</para><para>After reading the above, you may ask yourself if this is all we can do to accelerate <application>PHP-Nuke</application> with caching - and the answer is: of course not!</para><para>jpcache (<xref linkend="jpcache">) enables caching of the whole page. Remember, we edited index.<indexterm><primary>index</primary></indexterm>php to set a different cache expiration time for logged and not logged-in users. The idea behind this was that a user that is not logged in will not have access to most of the dynamic features of PHP-Nuke, thus making caching of the whole page for longer intervalls an acceptable compromise between freshness of content and speed of page generation.</para><para>But how about our logged-in users? Wouldn't it be nice if we could at least cache some <application>PHP-Nuke</application> blocks we know they don't change that often? This is indeed possible with <ulink url="http://pear.php.net/package-info.php?pacid=99">Cache-Lite</ulink> of the <ulink url="http://pear.php.net">PEAR library</ulink> from <acronym>PHP</acronym>.<indexterm><primary>PHP</primary></indexterm></para><sect3 id="cache-lite-installation"><title>Installation of Cache-Lite</title><para>Download Cache-Lite and extract it in the includes folder of your <application>PHP-Nuke</application> installation.<indexterm><primary>installation</primary></indexterm> </para><para>If your <acronym>PHP</acronym> does not include the PEAR library, you will need to download<indexterm><primary>download</primary></indexterm> download the base PEAR package too. Extract only the PEAR.<indexterm><primary>PEAR</primary></indexterm>php file and put it in the same folder as mainfile.php, i.e. your <application>PHP-Nuke</application> base folder. </para><para>Cache-Lite needs the PEAR.php file for its error-handling, so you may not notice that you need it until some error occurs. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject></para>
<para>If your <acronym>PHP</acronym> installation includes PEAR,<indexterm><primary>PEAR</primary></indexterm> you don't need to bother installing PEAR.<indexterm><primary>PEAR</primary></indexterm>php anywhere - it is already there, at the right place. But if your ISP does not include it, the above PEAR.<indexterm><primary>PEAR</primary></indexterm>php will do the trick.</para><para>That's all! You are now ready to use Cache-Lite.<indexterm><primary>Cache-Lite</primary></indexterm></para></sect3>
<sect3 id="cache-lite-use"><title>How to use Cache-Lite</title><para>Cache-Lite can easily be used to cache a <acronym>PHP</acronym> variable. The easiest application of this is to cache the $content variable of a block that does not change very often - and this is the majority of <application>PHP-Nuke</application> blocks! </para><para>To use Cache-Lite in a <application>PHP-Nuke</application> block,<indexterm><primary>block</primary></indexterm> open that block in your editor and put the following code (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=130">How to accelerate PHP-Nuke</ulink>):</para><screen><![CDATA[// include the Cache-Lite package
]]><![CDATA[require_once("includes/Cache_Lite/Lite.php");
]]><![CDATA[
]]><![CDATA[// set some variables
]]><![CDATA[$options = array(
]]><![CDATA[ "cacheDir" => "/tmp/Cache_Lite/",
]]><![CDATA[ "lifeTime" => 900
]]><![CDATA[);
]]><![CDATA[
]]><![CDATA[// create a Cache_Lite object
]]><![CDATA[$objCache = new Cache_Lite($options);
]]><![CDATA[
]]><![CDATA[// test if there exists a valid cache,
]]><![CDATA[// the <acronym>ID</acronym> will be the basename of the block
]]><![CDATA[$fileid = basename($blockfile,".php");
]]><![CDATA[if ($content = $objCache->get($fileid)) {
]]><![CDATA[// add a message indicating this is cached output
]]><![CDATA[ $content .= "\n[cached with ID=$fileid]";
]]><![CDATA[}
]]><![CDATA[else
]]><![CDATA[{
]]><![CDATA[// do the block's work here...
]]></screen><para><emphasis>after the lines</emphasis></para><screen><![CDATA[if (eregi("block-XXXXXXX.php",$PHP_SELF)) {
]]><![CDATA[ Header("Location: index.php");
]]><![CDATA[ die();
]]><![CDATA[}
]]></screen><para>What does the inserted code do?</para><itemizedlist><listitem><para>It includes Cache-Lite.<indexterm><primary>Cache-Lite</primary></indexterm> Note that in this example, Cache_Lite is a symbolic link to the actual directory the Lite.php file is in. I created this symbolic link myself, as I did not want to put a version-specific directory name in my code - I would have to change it each time I would upgrade Cache-Lite,<indexterm><primary>Cache-Lite</primary></indexterm> this way I will only need to change the symbolic link to show to the right directory.</para></listitem><listitem><para>It first sets the path to the cache directory, in this case /tmp/Cache_Lite/. The directory must exist and must be writable and readable by the web server.<indexterm><primary>server</primary></indexterm></para></listitem><listitem><para>Sets the cache expiration time intervall for the object we are going to cache, in this case to 900 seconds.<indexterm><primary>seconds</primary></indexterm></para></listitem><listitem><para>Creates a cache object with the above settings.<indexterm><primary>settings</primary></indexterm></para></listitem><listitem><para>Uses a computed &quot;file id&quot; as a key to identify the cached object (the cached<indexterm><primary>cached</primary></indexterm> $content variable). I have decided to use the basename of the <application>PHP-Nuke</application> block , i.e. the filename of the block without the &quot;.php&quot; ending, as the key for the $content variable. This way I don't have to change my code each time I insert the above lines in a new block.<indexterm><primary>block</primary></indexterm> The $key will be computed automatically and will be the basename of the block file. Since in <application>PHP-Nuke</application> blocks are guaranteed to have distinct names, this is a good choice.</para><para>$blockfile is a variable that is computed by <application>PHP-Nuke</application> in mainfile.php,<indexterm><primary>mainfile.php</primary></indexterm> in function blocks():</para><screen><![CDATA[$sql = "SELECT bid, bkey, title, content, url, blockfile, view FROM ".$prefix."_blocks
]]><![CDATA[WHERE bposition='$pos' AND active='1' $querylang ORDER BY weight ASC";
]]><![CDATA[$result = $db->sql_query($sql);
]]><![CDATA[while($row = $db->sql_fetchrow($result)) {
]]><![CDATA[ $bid = $row[bid];
]]><![CDATA[ $title = $row[title];
]]><![CDATA[ $content = $row[content];
]]><![CDATA[ $url = $row[url];
]]><![CDATA[ $blockfile = $row[blockfile];
]]></screen><para>The value of $blockfile is then passed through to the individual block:<indexterm><primary>block</primary></indexterm> it is passed to function render_blocks() (in mainfile.php again), which in turn renders the block using the blockfileinc() function.<indexterm><primary>function</primary></indexterm> </para><tip>
<title> What to do if the cache <acronym>ID</acronym> is empty</title>
<para>
Looking at the blockfileinc() function in mainfile.php, you can see that it uses the functions themecenterbox(() and themesidebox() for blocks that don't have a filename - and, of course, it does not pass the (empty) blockfile parameter. Thus, if you see that the above code for the block prints an empty cache ID, then you will know that you are using a block without a filename (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?p=1893">empty cache <acronym>ID</acronym> and Cache-Lite</ulink>).
</para>
<para>
The quick solution is to explicitly set the fileid variable to some arbitrary value in you block code. However, you should check to find out why your block does not posess a filename (e.g. it could be an RSS block - we describe these in <xref linkend="administration-functions"> and <xref linkend="fig-blocks">).
</para>
</tip>
</listitem><listitem><para>If a valid cached copy of the object identified by the key exists, it is fetched and fed into the $content variable of the block.<indexterm><primary>block</primary></indexterm> I issue an echo to print the cache <acronym>ID</acronym> (the key) in this case,<indexterm><primary>case</primary></indexterm> just for the start, to give me some idea of how (and if at all) this works. Of course, you can comment the echo later.</para></listitem><listitem><para>In case the cache misses the object (or expiration time is over), you wil have to compute $content from scratch.<indexterm><primary>scratch</primary></indexterm> Put your normal code here.</para></listitem></itemizedlist><para>Of course, we are not done yet - after we compute $content in our block, we will want to cache it for future use. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject></para>
<para>Thus, after the end of your computations and before you close the block<indexterm><primary>block</primary></indexterm> with &quot;?&gt;&quot;, put the following to instruct Cache-Lite to cache your $content:</para><screen><![CDATA[// ...and save it in the cache for future use
]]><![CDATA[$objCache->save($content, $fileid);
]]><![CDATA[}
]]></screen><para>This closes the IF-statement we opened with the previous block of lines. It caches the $content variable in our cache object, using as identifier<indexterm><primary>identifier</primary></indexterm> the file <acronym>ID</acronym> we derived from the block's filename.<indexterm><primary>filename</primary></indexterm> You have to put these two blocks of lines in every <application>PHP-Nuke</application> block you plan to cache,<indexterm><primary>cache</primary></indexterm> but the work is worth it!</para><para>The complete code for your cached block should thus look like:</para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[if (eregi("block-XXXXXXX.php",$PHP_SELF)) {
]]><![CDATA[ Header("Location: index.php");
]]><![CDATA[ die();
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[// include the Cache-Lite package
]]><![CDATA[require_once("includes/Cache_Lite/Lite.php");
]]><![CDATA[
]]><![CDATA[// set some variables
]]><![CDATA[$options = array(
]]><![CDATA[ "cacheDir" => "/tmp/Cache_Lite/",
]]><![CDATA[ "lifeTime" => 900
]]><![CDATA[);
]]><![CDATA[
]]><![CDATA[// create a Cache_Lite object
]]><![CDATA[$objCache = new Cache_Lite($options);
]]><![CDATA[
]]><![CDATA[// test if there exists a valid cache,
]]><![CDATA[// the <acronym>ID</acronym> will be the basename of the block
]]><![CDATA[$fileid = basename($blockfile,".php");
]]><![CDATA[if ($content = $objCache->get($fileid)) {
]]><![CDATA[ // add a message indicating this is cached output
]]><![CDATA[ $content .= "\n[cached with ID=$fileid]";
]]><![CDATA[}
]]><![CDATA[else
]]><![CDATA[{
]]><![CDATA[ // do the whole work here...
]]><![CDATA[
]]><![CDATA[-------> Your original code goes here <-------
]]><![CDATA[
]]><![CDATA[ // ...and save it in the cache for future use
]]><![CDATA[ $objCache->save($content, $fileid);
]]><![CDATA[}
]]><![CDATA[?>
]]></screen><para>If something goes wrong and your block is not being cached,<indexterm><primary>cached</primary></indexterm> check the following (<ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=130">How to accelerate PHP-Nuke</ulink>):</para><itemizedlist><listitem><para>Do you have the PEAR.php?<indexterm><primary>PEAR.php</primary></indexterm></para></listitem><listitem><para>Where did you install the Lite.php file? </para></listitem><listitem><para>Did you install it in includes/Cache_Lite/Lite.php,<indexterm><primary>Lite.php</primary></indexterm> as I suggested?</para></listitem><listitem><para>Did you enter the right path to Lite.php in the block you are trying to cache?<indexterm><primary>cache</primary></indexterm></para></listitem><listitem><para>Did you follow my example for a cached block above?</para></listitem><listitem><para>If you did, do you have the right path in the line</para><screen><![CDATA[require_once("includes/Cache_Lite/Lite.php");
]]></screen><para>of that example?</para></listitem></itemizedlist><para>For a more in-depth tutorial on Cache-Lite,<indexterm><primary>Cache-Lite</primary></indexterm> see <ulink url="http://www.devshed.com/Server_Side/PHP/PHP_Cache_Lite">Caching With <acronym>PHP</acronym> Cache_Lite</ulink>.</para><para>You can use both jpcache and Cache-Lite together in a cache strategy that caches the whole page with jpcache when a user is not logged-in,<indexterm><primary>logged-in</primary></indexterm> but caches the least changing blocks (probably most of them) with Cache-Lite when he is. Such a strategy allows enough flexibility and room for experimentation and brings a considerable acceleration to your PHP-Nuke, without, on the other hand, requiring any access to the internals of your <acronym>PHP</acronym> installation<indexterm><primary>installation</primary></indexterm> - something that you will need, if you want to try the ultimate approach to caching , which we will present you in <xref linkend="Turck-MMCache">.</para></sect3>
</sect2>
<sect2 id="Turck-MMCache"><title>Turck MMCache</title><para>
<figure id="fig-mmcache">
<title>
Turck MMCache.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1181;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1181;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1181;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1181;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Turck MMCache.</phrase>
</textobject>
<caption>
<para>Turck MMCache.</para>
</caption>
</mediaobject>
</figure>
</para><para>As we know, <acronym>PHP</acronym> is an interpreted language. The <acronym>PHP</acronym> interpreter compiles your scripts each time you call them. However, the <acronym>PHP</acronym> code itself may not change that often in your scripts. Having to compile the code on each call wastes your CPU's time. That's where the idea of caching the <acronym>PHP</acronym> code (and not only the HTML content) comes in (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=130">How to accelerate PHP-Nuke</ulink>). </para><para>The idea of <acronym>PHP</acronym> code caching lies in the basis of many commercial <acronym>PHP</acronym> accelerators, like </para><itemizedlist><listitem><para><ulink url="http://www.zend.com">Zend Performance Suite</ulink> </para></listitem><listitem><para><ulink url="http://www.php-accelerator.co.uk">PHP Accelerator</ulink> </para></listitem><listitem><para><ulink url="http://apc.communityconnect.com">Alternative <acronym>PHP</acronym> Cache</ulink> </para></listitem><listitem><para><ulink url="http://www.bwcache.bware.it">AfterBurner Cache</ulink> </para></listitem></itemizedlist><para>Hopefully, there is a free open source alternative: <ulink url="http://www.turcksoft.com/en/e_mmc.htm">Turck MMCache</ulink>, a product under the GPL Licence.<indexterm><primary>Licence</primary></indexterm> </para><para>Turck MMCache is a free open source <acronym>PHP</acronym> accelerator, optimizer,<indexterm><primary>optimizer</primary></indexterm> encoder and dynamic content cache for <acronym>PHP</acronym>.<indexterm><primary>PHP</primary></indexterm> It increases performance of <acronym>PHP</acronym> scripts by caching them in compiled state, so that the overhead of compiling is almost completely eliminated. Also it uses some optimizations to speed up execution of <acronym>PHP</acronym> scripts. Turck MMCache typically reduces server load and increases the speed of your <acronym>PHP</acronym> code by 1-10 times!</para><para>Download the newest version (currently 2.4.6) from the <ulink url="http://sourceforge.net/project/showfiles.php?group_id=69426">Turck MMCache download page at Sourceforge</ulink>. There are precompiled binaries for Windows,<indexterm><primary>Windows</primary></indexterm> as well as source packages for <productname>Linux</productname> and other operating systems.</para><para>Before you rush and download it though, let me bring to your attention that the approach taken by a code accelerator like MMCache requires that you install it as a so-called &quot;PHP extension&quot;. You will also be configuring options like the amount of shared memory that you want allocated to MMCache,<indexterm><primary>MMCache</primary></indexterm> in order to use it for caching. These steps are normally beyond the reach of mass hosting accounts on ISPs,<indexterm><primary>ISPs</primary></indexterm> so you may be out of luck. However, if you own the web server,<indexterm><primary>server</primary></indexterm> or have administration access to it, then MMCache is for you - rush to the download page and get it!</para><sect3 id="Turck-MMCache-installation"><title>Installation of Turck MMCache</title><para>In the following, I will describe the installation process of Turck MMCache<indexterm><primary>MMCache</primary></indexterm> for Linux:<indexterm><primary>Linux</primary></indexterm></para><itemizedlist><listitem><para>Login as root.<indexterm><primary>root</primary></indexterm></para></listitem><listitem><para>Change to a directory that is appropriate for holding source code. In Linux,<indexterm><primary>Linux</primary></indexterm> this is /usr/src:</para><screen><![CDATA[cd /usr/src
]]></screen></listitem><listitem><para>Extract the package:</para><screen><![CDATA[tar -xzvf /usr/cdimage/source/turck-mmcache-2.4.6.tar.gz
]]></screen></listitem><listitem><para>It creates an folder with all files. Change to that folder:</para><screen><![CDATA[cd turck-mmcache-2.4.6
]]></screen></listitem><listitem><para>Find the place where the phpize program is installed on your system.<indexterm><primary>system</primary></indexterm> For this, type:</para><screen><![CDATA[which phpize
]]></screen></listitem><listitem><para>Mine is on /usr/bin, as you can see from the output:</para><screen><![CDATA[# which phpize
]]><![CDATA[/usr/bin/phpize
]]></screen></listitem><listitem><para>so what is before the &quot;/bin&quot; is my PHP_PREFIX.<indexterm><primary>PHP_PREFIX</primary></indexterm> In this case &ldquo;/usr&rdquo;. Type the following:</para><screen><![CDATA[export PHP_PREFIX="/usr"
]]><![CDATA[$PHP_PREFIX/bin/phpize
]]></screen><para>You get the output:</para><screen><![CDATA[autoheader: `config.h.in' is created
]]><![CDATA[You should update your `aclocal.m4' by running aclocal.
]]></screen><para>so you run</para><screen><![CDATA[aclocal
]]></screen></listitem><listitem><para>Now you are ready to create the Makefile with the configure script:</para><screen><![CDATA[./configure --enable-mmcache=shared --with-php-config=$PHP_PREFIX/bin/php-config
]]></screen></listitem><listitem><para>After that, the Makefile is there and you can do (you must be root for the last step)</para><screen><![CDATA[make
]]><![CDATA[make install
]]></screen></listitem></itemizedlist><para>This will finish installation of Turck MMCache on your server.<indexterm><primary>server</primary></indexterm></para></sect3>
<sect3 id="Turck-MMCache-configuration"><title>Configuration of Turck MMCache</title><para>After installation,<indexterm><primary>installation</primary></indexterm> you need to configure MMCache:</para><para>Open the php.ini file (/etc/php.ini), find the &quot;extensions&quot; section and put the following there:</para><screen><![CDATA[[extension section]
]]><![CDATA[... various other extensions
]]><![CDATA[extension="mmcache.so"
]]><![CDATA[mmcache.shm_size="16"
]]><![CDATA[mmcache.cache_dir="/tmp/mmcache"
]]><![CDATA[mmcache.enable="1"
]]><![CDATA[mmcache.optimizer="1"
]]><![CDATA[mmcache.check_mtime="1"
]]><![CDATA[mmcache.debug="0"
]]><![CDATA[mmcache.filter=""
]]><![CDATA[mmcache.shm_max="0"
]]><![CDATA[mmcache.shm_ttl="0"
]]><![CDATA[mmcache.shm_prune_period="0"
]]><![CDATA[mmcache.shm_only="0"
]]><![CDATA[mmcache.compress="0"
]]><![CDATA[; end of extension section
]]></screen><para>MMCache uses shared memory for caching, as opposed to disk space.<indexterm><primary>space</primary></indexterm> This is a reason why it is so fast. The mmcache.<indexterm><primary>cache</primary></indexterm>shm_size option defines how much shared memory (in MBytes) it should use for caching.</para><para>Again, you need a cache directory too, which is what mmcache.<indexterm><primary>cache</primary></indexterm>cache_dir is for. Again, the cache directory should be writable and readable by your web server.<indexterm><primary>server</primary></indexterm></para><para>You can read about the other options in the <ulink url="http://www.turcksoft.com/en/e_mmc.htm">Turck MMCache Homepage</ulink>. For our purposes, you can leave them at their values as in the example above.</para><para>This completes the configuration of MMCache. We still have to talk about its use - but that's easy, see the next section. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
<tip>
<title>
Turck MMCache on a virtual server
</title>
<para>
Question: I am on a virtual server and should not interfere with the other domains hosted there. How do I configure MMCache in this situation?
</para>
<para>
Answer: Compile MMCache and put it into the extensions directory. Configure php.ini to utilize the extension but set mmcache.optimizer, .compress and .enable all to FALSE.
</para>
<para>
Then a .htaccess file (see <xref linkend="htaccess-file">) in your own webspace and use:
</para>
<screen>
<![CDATA[php_value 'mmcache.enable' '1']]>
<![CDATA[php_value 'mmcache.optimizer' '1']]>
<![CDATA[php_value 'mmcache.compress' 1']]>
</screen>
<para>
This should do the trick.
</para>
</tip>
</sect3>
<sect3 id="Turck-MMCache-use"><title>How to use Turck MMCache</title><para>By following the configuartion steps above, MMCache already works for you: it compiles <acronym>PHP</acronym> code and caches it. Whenever a script's code changes, it recompiles it and caches it again. You should already see a noticeable improvement in your response times because of this.</para><para>But there is more you can do with MMCache:<indexterm><primary>MMCache</primary></indexterm> you can cache a whole page, like with jpcache (<xref linkend="jpcache">), or individual parts of them, like with Cache-Lite (<xref linkend="cache-lite">). Since jpcache uses disk space for caching the whole page, you can replace it by MMCache's functionality,<indexterm><primary>functionality</primary></indexterm> which uses shared memory and could thus be up to 5 times faster. Here's how you do it (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=130">How to accelerate PHP-Nuke</ulink>):</para><para>Open the index.<indexterm><primary>index</primary></indexterm>php file and change the code we put there for jpcache (see a previous post) as follows:</para><screen><![CDATA[require_once("mainfile.php");
]]><![CDATA[if (!isset($user)) {
]]><![CDATA[ $cachetimeout=900;
]]><![CDATA[ mmcache_cache_page($_SERVER['PHP_SELF'].'?GET='.serialize($_GET), $cachetimeout);
]]><![CDATA[} else {
]]><![CDATA[ $cachetimeout=-1;
]]><![CDATA[}
]]><![CDATA[# require_once "includes/jpcache/jpcache.php";
]]></screen><para>As you can see, we commented the jpcache inclusion line and put a call to mmcache_cache_page with the same cache timeout. This will do exactly what jpcache was doing previously - cache the whole page in case the user is not logged-in and leave it uncached in case he is, so that Cache-Lite can cache parts of it. But due to the shared memory implementation, we are going the get an extra speed kick out of it. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_cool.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_cool.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_cool.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_cool.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject></para>
<para>mmcache_cache_page is only one of many MMCache functions you can use in your blocks and modules to speed up things. Some other interesting ones are:</para><itemizedlist><listitem><para>mmcache_set_session_handlers(): install the MMCache session handlers. Since <acronym>PHP</acronym> 4.2.0 you can install MMCache session handlers in &quot;php.ini&quot;<indexterm><primary>php.ini</primary></indexterm> by</para><screen><![CDATA[session.save_handler=mmcache
]]></screen></listitem><listitem><para>mmcache_cache_output($key,<indexterm><primary>key</primary></indexterm> $eval_code, $ttl=0): caches the output of $eval_code in shared memory for $ttl seconds.<indexterm><primary>seconds</primary></indexterm> Output can be removed from cache by calling mmcach_rm() with the same $key.<indexterm><primary>key</primary></indexterm> For Example:</para><screen><![CDATA[<?php mmcache_cache_output('test', 'echo time(); phpinfo();', 30); ?>
]]></screen></listitem><listitem><para>mmcache_cache_result($key,<indexterm><primary>key</primary></indexterm> $eval_code, $ttl=0): caches the result of $eval_code in shared memory for $ttl seconds.<indexterm><primary>seconds</primary></indexterm> Result can be removed from cache by calling mmcach_rm() with the same $key.<indexterm><primary>key</primary></indexterm> For Example:</para><screen><![CDATA[<?php mmcache_cache_output('test', 'time()." Hello";', 30); ?>
]]></screen></listitem></itemizedlist><para>There are other uses of MMCache, like its use as an encoder to hide your precious <acronym>PHP</acronym> scripts from the spying eyes of competitors - but we are talking open source here, aren't we? <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
</sect3>
</sect2>
<sect2 id="Caching-PHP-Nuke-Conclusion"><title>Caching PHP-Nuke: Conclusion</title><para>We have seen three approaches to <application>PHP-Nuke</application> acceleration in the previous sections:</para><itemizedlist><listitem><para>jpcache (see <xref linkend="jpcache">) can cache and compress a whole page - on disk.<indexterm><primary>disk</primary></indexterm></para></listitem><listitem><para>Cache-Lite (see <xref linkend="cache-lite">) can cache and compress a whole page or individual <application>PHP-Nuke</application> blocks, modules,<indexterm><primary>modules</primary></indexterm> variables - on disk (or shared memory too? FIXME:<indexterm><primary>FIXME</primary></indexterm> someone please correct me here!).</para></listitem><listitem><para>Turck MMCache (see <xref linkend="Turck-MMCache">) can cache and compress all of the above, plus can do encoding - all in shared memory!</para></listitem></itemizedlist><para>So which tool is the right one for you?</para><para>There are a lot of combinations one could try there and without serious testing it is not easy to answer this question definitely. However, from what we have seen already in the previous posts,<indexterm><primary>posts</primary></indexterm> we can derive some strategies (see also <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=130">How to accelerate PHP-Nuke</ulink>):</para><itemizedlist><listitem><para>If you don't have administration access to your web server,<indexterm><primary>server</primary></indexterm> you are left with jpcache and Cache-Lite.<indexterm><primary>Cache-Lite</primary></indexterm> Use a combination of them as outlined above, caching whole pages with jpcache<indexterm><primary>jpcache</primary></indexterm> and individual blocks/modules with Cache-Lite.<indexterm><primary>Cache-Lite</primary></indexterm> It's a strategic decision when to use which one - one you will have to make yourself.</para></listitem><listitem><para>If you do have administration access to your web server,<indexterm><primary>server</primary></indexterm> MMCache is the way to go. You can use it to cache <acronym>PHP</acronym> code and - optionally - a whole page content or just part of it. Whether you should prefer Cache-Lite for the latter, or decide to use MMCache,<indexterm><primary>MMCache</primary></indexterm> is something that probably only tests can show.</para></listitem><listitem><para>Ease of deployment can also play a role: with MMCache,<indexterm><primary>MMCache</primary></indexterm> you add a line, with Cache-Lite a whole block of lines, to each <application>PHP-Nuke</application> module or block you wish to cache.<indexterm><primary>cache</primary></indexterm> On the other hand, Cache-Lite may live up to its name and prove itself to be really lightweight in some (or all) situations.<indexterm><primary>ations</primary></indexterm> Again, you wll have to test.<indexterm><primary>test</primary></indexterm></para></listitem></itemizedlist></sect2>
</sect1>
</chapter>
<chapter id="optimizing-php-nuke"><title>Optimizing <application>PHP-Nuke</application> </title><para>Once your <application>PHP-Nuke</application> site is up and running, you can relax and watch it grow. But as it grows, your expectations will grow too: better visibility with the search engines, better protection of your content, better response<indexterm><primary>response</primary></indexterm> times from the database - in short, the idea of optimization will start occupying your thoughts more and more. In this chapter we cover some advanced optimization topics:<indexterm><primary>topics</primary></indexterm></para><itemizedlist><listitem><para>Search engines and dynamic URLs (<xref linkend="search-engines-and-dynamic-URLs">),</para></listitem><listitem><para>mod_rewrite (<xref linkend="mod-rewrite">),</para></listitem><listitem><para>Regular expressions (<xref linkend="regular-expressions">),</para></listitem><listitem><para>The .htaccess file (<xref linkend="htaccess-file">),</para></listitem><listitem><para>How to make <application>PHP-Nuke</application> search engine friendly (<xref linkend="make-php-nuke-search-engine-friendly">),</para></listitem><listitem><para>How to make <application>PHP-Nuke</application> hot link stealth (<xref linkend="make-PHP-Nuke-hot-link-stealth">),</para></listitem><listitem><para>How to make a dynamic CSS (<xref linkend="make-dynamic-CSS">),</para></listitem><listitem><para>How to proceed when MySQL is slow (<xref linkend="proceed-when-MySQL-slow">).</para></listitem></itemizedlist><sect1 id="search-engines-and-dynamic-URLs"><title>Search engines and dynamic URLs</title><para>The ability to transfer information from one script to another is essential to modern dynamic web pages. Usually, the scripts will use the well-known GET method for this purpose. For example, to edit your personal information,<indexterm><primary>information</primary></indexterm> <application>PHP-Nuke</application> calls the Your_Account module with an URL like:</para><screen><![CDATA[http://www.yourdomain.com/modules.php?name=Your_Account&op=edituser
]]></screen><para>The &quot;name&quot; and &quot;op&quot; are so-called URL parameters and are passed to the modules.<indexterm><primary>modules</primary></indexterm>php script through the GET method. This is what happens besides the scenes:</para><para>The modules.<indexterm><primary>modules</primary></indexterm>php file includes mainfile.php, as practically every piece of <application>PHP-Nuke</application> code does, directly or indirectly (see <xref linkend="block-creation">, for blocks and <xref linkend="creating-modules">, for modules). In mainfile.php,<indexterm><primary>mainfile.php</primary></indexterm> one of the first things that is checked, is whether you have register_globals set to OFF in your php.ini:<indexterm><primary>php.ini</primary></indexterm></para><screen><![CDATA[if (!ini_get("register_globals")) {
]]><![CDATA[ import_request_variables('GPC');
]]><![CDATA[}
]]></screen><para>If it is, the above code will call <ulink url="http://www.php.net/manual/en/function.import-request-variables.php">import_request_variables</ulink> and import all GET variables (i.e. &quot;name&quot; and &quot;op&quot; in the example) in the $_GET array. Using the types parameter,<indexterm><primary>parameter</primary></indexterm> you can specify which request variables to import with import_request_variables . You can use 'G', 'P' and 'C' characters respectively for GET,<indexterm><primary>GET</primary></indexterm> POST and Cookie,<indexterm><primary>Cookie</primary></indexterm> as in the example from mainfile.php above.</para><para>The code goes on to submit each variable in the $_GET array to a series<indexterm><primary>series</primary></indexterm> of checks that should guard against any misuse of the parameters for cracking<indexterm><primary>cracking</primary></indexterm> purposes (see <xref linkend="security-audit">), but this is not going to be pursued further here (see <xref linkend="how-secure-is-php-nuke"> for the security perspective on PHP-Nuke). We are rather going to concentrate on a different aspect of URL parameter<indexterm><primary>parameter</primary></indexterm> passing: the GET method of transferring parameters between scripts makes your web pages unfriendly for search engines - up to the point that they may not be indexed at all!</para><sect2 id="search-engines-and-GET-method"><title>Search engines and the GET method</title><para>When a search engine spider encounters an URL with many parameters while indexing your pages, it will ignore the URL and not index that particular page. Just how many parameters are too many for a search engine,<indexterm><primary>engine</primary></indexterm> is difficult to say. The search engines are deliberately vague on this point, just as they are on almost every other point regarding their algorithms.<indexterm><primary>algorithms</primary></indexterm> For example, <ulink url="http://www.google.com">Google</ulink> states the following in its <ulink url="http://www.google.com/webmasters/guidelines.html">Guidelines for Webmasters</ulink>:</para><blockquote><para>Allow search bots to crawl your sites without session ID's or arguments that track their path through the site. These techniques are useful for tracking individual user behavior, but the access pattern of bots is entirely different. Using these techniques may result in incomplete indexing of your site, as bots may not be able to eliminate URLs that look different but actually point to the same page. </para></blockquote><para>This does not mean that Google will not spider dynamic pages at all, however (although this seems to have been the case in the past, though). Somewhere in the first months of 2003, Google's algoritms became intelligent enough to tackle the tricky problem of dynamic URLs - well, at least partly, see <ulink url="http://www.webmasterworld.com/forum3/12370.htm">Google is now better at spidering dynamic sites</ulink>. Observational evidence suggests that Google will now index a page whose URL contains no more than 2-3 parameters with short names (URLs with 2 parameters is the maximum for Google right now, said Marissa Mayer of Google<indexterm><primary>Google</primary></indexterm> in the <ulink url="http://www.seroundtable.com/archives/000024.html">Search Engines Strategies Chicago December 10th Day Two</ulink>, Dec. 10th 2003 ). </para><para>Still, the problem remains for URLs with many parameters, as well as session<indexterm><primary>session</primary></indexterm> IDs. A page that uses session IDs can generate an infinite amount of pages for a spider to visit. These types of pages are blocked from being indexed not only by Google,<indexterm><primary>Google</primary></indexterm> but from other search engines as well.</para><para>If a bot ignores a page due to a session <acronym>ID</acronym> or a large number of GET parameters on the URL,<indexterm><primary>URL</primary></indexterm> it will also ignore all pages referenced by that page (unless it finds its way to them through some other link that it can follow). Since every <application>PHP-Nuke</application> module is accessible through an URL of the form</para><screen><![CDATA[http://www.yourdomain.com/modules.php?name=Your_Account&op=edituser
]]></screen><para>and the <application>PHP-Nuke</application> forums with at least 4 URL parameters, one of which is a session ID,</para><screen><![CDATA[http://www.yourdomain.com/modules.php?name=Forums&file=viewforum&f=1
]]><![CDATA[&sid=9bd5f57e4615bbd6d9e2677ea7cbb781
]]></screen><para>you run the risk that the majority of your pages will be unknown to the search engines. As a rule of thumb we can say that, if this happens, it will cost you two thirds of your external referrals<indexterm><primary>referrals</primary></indexterm><footnote><para>A typical website will get about two thirds of its external traffic from search engines and one third from sites that link directly to it. Of course, your mileage may vary.</para></footnote>. This can cost you your web existence and can mean the difference between success and failure for your website!</para><para>Why? Because search engines create multiple entry points into your website,<indexterm><primary>website</primary></indexterm> a fact that many people fail to realize. Most people you know may be coming to your website through its main index.php<indexterm><primary>index.php</primary></indexterm> page, mainly because it is easier to remember, or it's just the web address you printed on the business card you gave to them. But a well-indexed website will soon begin driving traffic to deeper located pages. The search engines have rendered elaborately crafted entry pages almost obsolete:<indexterm><primary>obsolete</primary></indexterm> today, every page of your website can be an entry page.</para><para>It is also overseen by the average webmaster that these interior pages often draw a different kind of users than the index page: users arriving there are much more qualified because they are looking for information specific to a certain topic. Because they are looking for very specific information,<indexterm><primary>information</primary></indexterm> they are also more likely to convert on a sale or action that you have prepared for them.</para><para>If the search engines are not able to spider your dynamic content because of the GET parameters in the URL,<indexterm><primary>URL</primary></indexterm> you are losing - these more qualified visitors often won't find your website.<indexterm><primary>website</primary></indexterm> Thus it is very important that you find a way to make as much of your website<indexterm><primary>website</primary></indexterm> as possible visible to the search engines.</para><para>If you budget affords it, you can choose the lazy way: some serach engines, like Inktomi (FIXM: URL!), offer a Paid Inclusion Program. In a Paid Inclusion Program, it is <emphasis>you</emphasis> who submits a list of URLs to the search engine to crawl, not the search<indexterm><primary>search</primary></indexterm> engine that finds them automatically. This way, the search engine can be sure that the list of URLs you submitted contains real content that is of importance to you and that none of the URLs contain duplicate content of one and the same page (something that can easy happen with session IDs and an automatic spider,<indexterm><primary>spider</primary></indexterm> for example). </para><para>On the plus side of a Paid Inclusion Program, you will get your pages indexed,<indexterm><primary>indexed</primary></indexterm> the URLs will be the correct ones and the world will be able to search<indexterm><primary>search</primary></indexterm> and find you. The downside is that you have to pay for each and every URL you want to have indexed.<indexterm><primary>indexed</primary></indexterm> If this strains your budget, you will have to search for alternatives.<indexterm><primary>alternatives</primary></indexterm></para><para>It turns out that such an alternative exists, thanks to the Swiss-Army-Knife<indexterm><primary>Swiss-Army-Knife</primary></indexterm> of URL manipulation that is called mod_rewrite.<indexterm><primary>rewrite</primary></indexterm></para></sect2>
</sect1>
<sect1 id="mod-rewrite"><title>mod_rewrite</title><para>You will probably find <ulink url="http://httpd.apache.org/docs/mod/mod_rewrite.html">mod_rewrite</ulink> already installed by your ISP on your web server.<indexterm><primary>server</primary></indexterm> This module uses a rule-based rewriting engine (based on a regular-expression<indexterm><primary>regular-expression</primary></indexterm> parser) to rewrite requested URLs on the fly. It supports an unlimited number of rules and an unlimited number of attached rule conditions for each rule to provide a really flexible and powerful URL manipulation mechanism. The URL manipulations can depend on various tests, for instance server<indexterm><primary>server</primary></indexterm> variables, environment variables, HTTP headers,<indexterm><primary>headers</primary></indexterm> time stamps and even external database lookups in various formats can be used to achieve a really granular<indexterm><primary>granular</primary></indexterm> URL matching (see the <ulink url="http://httpd.apache.org/docs/mod/mod_rewrite.html">Apache Documentation of mod_rewrite</ulink>).</para><caution>
<title>
Find out if you have mod_rewrite installed first!
</title>
<para>
There is little meaning in trying to implement an URL manipulation solution, if your ISP has not installed mod_rewrite on your web server - so you better find out before you start. The easiest way is to call your ISP and ask. If this appears to be more time consuming than you thought, you can also find it out yourself if you save the following 3-liner
</para>
<screen>
<![CDATA[<?]]>
<![CDATA[phpinfo()]]>
<![CDATA[?>]]>
</screen>
<para>
in a file called test.php, then upload it to you web server and open it with your browser. It will display a wealth of information about your <acronym>PHP</acronym> configuration (that's why you should delete it, or at least restrict access to it by putting it in a .htaccess password protected directory, when you are done). Among others, you will see a section called &ldquo;apache&rdquo;. Search for &ldquo;mod_rewrite&rdquo; in the &ldquo;Loaded Modules&rdquo; part. If you find it, mod_rewrite is up and running on your web server.
</para>
</caution>
<para>
<figure id="fig-mod-rewrite-phpinfo">
<title>
Apache section of the phpinfo() output: mod_rewrite is loaded.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1182;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1182;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1182;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1182;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Apache section of the phpinfo() output: mod_rewrite is loaded.</phrase>
</textobject>
<caption>
<para>Apache section of the phpinfo() output: mod_rewrite is loaded.</para>
</caption>
</mediaobject>
</figure>
</para><para>The internal processing of this module is very complex but needs to be explained once even to the average user to avoid common mistakes and to let you exploit<indexterm><primary>exploit</primary></indexterm> its full functionality.<indexterm><primary>functionality</primary></indexterm> For this we use the <ulink url="http://httpd.apache.org/docs/mod/mod_rewrite.html">Apache Documentation of mod_rewrite</ulink>. Of course, there is little point in reproducing it here in whole, so you are referred to it for all the gory details.</para><para>Here we will cover:</para><itemizedlist><listitem><para>The mod_rewrite API phases (<xref linkend="mod-rewrite-API-phases">),</para></listitem><listitem><para>The mod_rewrite ruleset processing (<xref linkend="mod-rewrite-ruleset-processing">),</para></listitem><listitem><para>Quoting special characters (<xref linkend="mod-rewrite-quoting-special-characters">),</para></listitem><listitem><para>Regex backreference availability (<xref linkend="mod-rewrite-regex-backreferences">).</para></listitem></itemizedlist><sect2 id="mod-rewrite-API-phases"><title>API phases</title><para>First you have to understand that when Apache processes a HTTP request it does this in phases.<indexterm><primary>phases</primary></indexterm> A hook for each of these phases is provided by the Apache API.<indexterm><primary>API</primary></indexterm> Mod_rewrite uses two of these hooks:<indexterm><primary>hooks</primary></indexterm> the URL-to-filename translation hook which is used after the HTTP request has been read but before any authorization<indexterm><primary>authorization</primary></indexterm> starts and the Fixup hook which is triggered after the authorization phases<indexterm><primary>phases</primary></indexterm> and after the per-directory config files (.htaccess) have been read, but before the content handler is activated.<indexterm><primary>activated</primary></indexterm></para><para>So, after a request comes in and Apache has determined the corresponding server (or virtual server) the rewriting engine starts processing of all mod_rewrite directives from the per-server configuration in the URL-to-filename<indexterm><primary>filename</primary></indexterm> phase.<indexterm><primary>phase</primary></indexterm> A few steps later when the final data directories are found, the per-directory configuration directives of mod_rewrite are triggered in the Fixup phase.<indexterm><primary>phase</primary></indexterm> In both situations mod_rewrite rewrites URLs either to new URLs or to filenames, although there is no obvious distinction between them. This is a usage of the API which was not intended to be this way when the API was designed, but as of Apache 1.x this is the only way mod_rewrite<indexterm><primary>rewrite</primary></indexterm> can operate. To make this point more clear remember the following two points:</para><orderedlist><listitem><para><indexterm><primary>Enumerate</primary></indexterm>Although mod_rewrite rewrites URLs to URLs, URLs to filenames and even filenames to filenames, the API currently provides only a URL-to-filename hook.<indexterm><primary>hook</primary></indexterm> In Apache 2.0 the two missing hooks will be added to make the processing more clear. But this point has no drawbacks for the user, it is just a fact which should be remembered: Apache does more in the URL-to-filename hook than the API<indexterm><primary>API</primary></indexterm> intends for it.</para></listitem><listitem><para><indexterm><primary>Enumerate</primary></indexterm>Unbelievably mod_rewrite provides URL manipulations in per-directory context,<indexterm><primary>context</primary></indexterm> i.e., within .htaccess files, although these are reached a very long time after the URLs have been translated to filenames. It has to be this way because .htaccess files live in the filesystem,<indexterm><primary>system</primary></indexterm> so processing has already reached this stage. In other words:<indexterm><primary>words</primary></indexterm> According to the API phases at this time it is too late for any URL manipulations.<indexterm><primary>manipulations</primary></indexterm> To overcome this chicken and egg problem mod_rewrite uses a trick: When you manipulate a URL/filename in per-directory context mod_rewrite first rewrites the filename back to its corresponding URL (which is usually impossible, but see the Re writeBase directive below for the trick to achieve this) and then initiates a new internal sub-request with the new URL.<indexterm><primary>URL</primary></indexterm> This restarts processing of the API phases.<indexterm><primary>phases</primary></indexterm></para><para>Again mod_rewrite tries hard to make this complicated step totally transparent<indexterm><primary>parent</primary></indexterm> to the user, but you should remember here: While URL manipulations in per-server context are really fast and efficient, per-directory rewrites are slow and inefficient due to this chicken and egg problem. But on the other hand this is the only way mod_rewrite can provide (locally restricted) URL manipulations to the average user.</para></listitem></orderedlist><para>Don't forget these two points!</para></sect2>
<sect2 id="mod-rewrite-ruleset-processing"><title>Ruleset processing</title><para>Now when mod_rewrite is triggered in these two API phases,<indexterm><primary>phases</primary></indexterm> it reads the configured rulesets from its configuration structure (which itself was either created on start up for per-server context or during the directory walk of the Apache kernel for per-directory context). Then the URL rewriting engine is started with the contained ruleset (one or more rules together with their conditions). The operation of the URL rewriting engine itself is exactly the same for both configuration contexts. Only the final result processing is different.</para><para>The order of rules in the ruleset is important because the rewriting engine<indexterm><primary>engine</primary></indexterm> processes them in a special (and not very obvious) order. The rule is this: The rewriting engine loops through the ruleset rule by rule (RewriteRule directives) and when a particular rule matches it optionally loops through existing corresponding conditions (RewriteCond directives). For historical reasons the conditions are given first, and so the control<indexterm><primary>control</primary></indexterm> flow is a little bit long-winded. See <xref linkend="fig-mod-rewrite-control-flow"> for more details.</para><para>
<figure id="fig-mod-rewrite-control-flow">
<title>
mod_rewrite: The control flow through the rewriting ruleset
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1183;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1183;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1183;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1183;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>mod_rewrite: The control flow through the rewriting ruleset</phrase>
</textobject>
<caption>
<para>mod_rewrite: The control flow through the rewriting ruleset</para>
</caption>
</mediaobject>
</figure>
</para><para>As you can see, first the URL is matched against the Pattern of each rule. When it fails mod_rewrite immediately stops processing this rule and continues with the next rule. If the Pattern matches, mod_rewrite looks for corresponding rule conditions. If none are present, it just substitutes the URL with a new value which is constructed from the string Substitution and goes on with its rule-looping.<indexterm><primary>rule-looping</primary></indexterm> But if conditions exist, it starts an inner loop for processing them in the order that they are listed. For conditions the logic is different: we don't match a pattern against the current URL.<indexterm><primary>URL</primary></indexterm> Instead we first create a string TestString by expanding variables, back-references, map lookups,<indexterm><primary>lookups</primary></indexterm> etc. and then we try to match CondPattern against it. If the pattern doesn't match,<indexterm><primary>match</primary></indexterm> the complete set of conditions and the corresponding rule fails. If the pattern matches, then the next condition is processed until no more conditions are available. If all conditions match,<indexterm><primary>match</primary></indexterm> processing is continued with the substitution of the URL with Substitution.</para></sect2>
<sect2 id="mod-rewrite-quoting-special-characters"><title>Quoting special characters</title><para>As of Apache 1.3.20, special characters in TestString and Substitution strings<indexterm><primary>strings</primary></indexterm> can be escaped (that is, treated as normal characters without their usual special meaning) by prefixing them with a slosh ('\') character.<indexterm><primary>character</primary></indexterm> In other words,<indexterm><primary>words</primary></indexterm> you can include an actual dollar-sign character in a Substitution string by using '\$'; this keeps mod_rewrite from trying to treat it as a backreference.<indexterm><primary>backreference</primary></indexterm></para></sect2>
<sect2 id="mod-rewrite-regex-backreferences"><title>Regex backreference availability</title><para>One important thing here has to be remembered: Whenever you use parentheses in Pattern or in one of the CondPattern,<indexterm><primary>CondPattern</primary></indexterm> back-references are internally created which can be used with the strings $N and %N (see <xref linkend="regular-expressions">). These are available for creating the strings Substitution and TestString.<indexterm><primary>TestString</primary></indexterm> <xref linkend="fig-mod-rewrite-back-reference"> shows to which locations the backreferences are transfered for expansion.</para><para>
<figure id="fig-mod-rewrite-back-reference">
<title>
mod_rewrite: The back-reference flow through a rule.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1184;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1184;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1184;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1184;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>mod_rewrite: The back-reference flow through a rule.</phrase>
</textobject>
<caption>
<para>mod_rewrite: The back-reference flow through a rule.</para>
</caption>
</mediaobject>
</figure>
</para><para>We know this was a crash course on mod_rewrite's internal processing. But you will benefit from this knowledge when reading the following. mod_rewrite's behaviour can be controlled with numerous directives,<indexterm><primary>directives</primary></indexterm> they are all described in the <ulink url="http://httpd.apache.org/docs/mod/mod_rewrite.html">Apache Documentation of mod_rewrite</ulink>. Further, real world examples of mod_rewrite use are presented in the <ulink url="http://httpd.apache.org/docs/misc/rewriteguide.html">Apache URL Rewriting Guide</ulink>. </para><para>But besides the directives available for mod_rewrite,<indexterm><primary>rewrite</primary></indexterm> you will also need a grasp of regular expressions (<xref linkend="regular-expressions">) and the .htaccess file (<xref linkend="htaccess-file">) to understand the solution for a search engine friendly <application>PHP-Nuke</application> site that we will present later on, in <xref linkend="make-php-nuke-search-engine-friendly">.</para><para>Not so fast! &ldquo;Regular expression?&rdquo; Right. If you've used "wildcards" with MS-DOS or Windows, somefile.* or some?.exe for example, you already understand the concept. But regex (regular expressions) are much more powerful. And complex. Read on! <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject></para>
</sect2>
</sect1>
<sect1 id="regular-expressions"><title>Regular expressions</title><para>
<figure id="fig-regular-expressions">
<title>
Pattern matching with a regular expression.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1185;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1185;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1185;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1185;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Pattern matching with a regular expression.</phrase>
</textobject>
<caption>
<para>Pattern matching with a regular expression.</para>
</caption>
</mediaobject>
</figure>
</para><para>Regular expressions are used as &ldquo;templates&rdquo; that match patterns of text. For example, the regular expression for the pattern matching in <xref linkend="fig-regular-expressions"> is<footnote><para>The regular expression matches the HTML code for the text shown in <xref linkend="fig-regular-expressions">, where the capital letters A and C were enclosed in &lt;i&gt; tags. This makes it look more formidable than it actually is.</para></footnote></para><screen><![CDATA[\([Ii]f \|and \)*\(<i>[AC]\+<\/i>.\)\(and\)\?
]]></screen><para>To understand any URL manipulation solution to the problem of non-search-engine-friendly URLs, you have to get acquainted with Regular Expressions.<indexterm><primary>Expressions</primary></indexterm> To get you started, read <ulink url="http://etext.lib.virginia.edu/helpsheets/regex.html">Using Regular Expressions</ulink> and <ulink url="http://gnosis.cx/publish/programming/regular_expressions.html">Matching Patterns in Text</ulink>. We can only touch the basics here, for which we use material taken from <ulink url="http://www.tldp.org/LDP/abs/html/x12265.html">A Brief Introduction to Regular Expressions</ulink>:</para><para>An expression is a string of characters. Those characters that have an interpretation above and beyond their literal meaning are called metacharacters.<indexterm><primary>metacharacters</primary></indexterm> A quote symbol, for example, may denote speech by a person, ditto,<indexterm><primary>ditto</primary></indexterm> or a meta-meaning for the symbols that follow. Regular Expressions are sets of characters and/or metacharacters that UNIX<indexterm><primary>UNIX</primary></indexterm> endows with special features.<indexterm><primary>features</primary></indexterm></para><para>The main uses for Regular Expressions (REs) are text searches and string manipulation. An RE matches a single character or a set of characters (a substring or an entire string). </para><itemizedlist><listitem><para>The asterisk -- * -- matches any number of repeats of the character string or RE preceding it, including zero.<indexterm><primary>zero</primary></indexterm></para><screen><![CDATA["1133*" matches 11 + one or more 3's + possibly other characters: 113, 1133, 111312, and so forth.
]]></screen></listitem><listitem><para>The dot -- . -- matches any one character,<indexterm><primary>character</primary></indexterm> except a newline. [2]</para><screen><![CDATA["13." matches 13 + at least one of any character (including a space): 1133, 11333, but not 13 (additional character missing).
]]></screen></listitem><listitem><para>The caret -- ^ -- matches the beginning of a line, but sometimes, depending<indexterm><primary>pending</primary></indexterm> on context,<indexterm><primary>context</primary></indexterm> negates the meaning of a set of characters in an RE.</para></listitem><listitem><para>The dollar sign -- $ -- at the end of an RE matches the end of a line.</para></listitem><listitem><para>&quot;^$&quot; matches blank lines.</para></listitem><listitem><para>Brackets -- [...] -- enclose a set of characters to match in a single RE.</para><itemizedlist><listitem><para>&quot;[xyz]&quot; matches the characters x, y, or z.</para></listitem><listitem><para>&quot;[c-n]&quot; matches any of the characters in the range c to n.</para></listitem><listitem><para>&quot;[B-Pk-y]&quot; matches any of the characters in the ranges B to P and k to y.</para></listitem><listitem><para>&quot;[a-z0-9]&quot; matches any lowercase letter or any digit.<indexterm><primary>digit</primary></indexterm></para></listitem><listitem><para>&quot;[^b-d]&quot; matches all characters except those in the range b to d. This is an instance of ^ negating or inverting the meaning of the following RE (taking on a role similar to ! in a different context).</para></listitem><listitem><para>Combined sequences of bracketed characters match common word patterns.<indexterm><primary>patterns</primary></indexterm> &quot;[Yy][Ee][Ss]&quot; matches yes, Yes, YES, yEs, and so forth. &quot;[0-9][0-9][0-9]-[0-9][0-9]-[0-9</para></listitem><listitem><para>][0-9][0-9][0-9]&quot; matches any Social Security number.</para></listitem></itemizedlist></listitem><listitem><para>The backslash -- \ -- escapes a special character,<indexterm><primary>character</primary></indexterm> which means that character gets interpreted literally.</para><itemizedlist><listitem><para>A &quot;\$&quot; reverts back to its literal meaning of &quot;$&quot;, rather than its RE meaning of end-of-line. Likewise a &quot;\\&quot; has the literal meaning of &quot;\&quot;.</para></listitem><listitem><para>Escaped &quot;angle brackets&quot; -- \&lt;...\&gt; -- mark word boundaries. The angle brackets must be escaped, since otherwise they have only their literal character meaning:</para><screen><![CDATA["\<the\>" matches the word "the", but not the words "them", "there", "other", etc.
]]></screen></listitem></itemizedlist></listitem><listitem><para>The question mark -- ? -- matches zero or one of the previous RE. It is generally used for matching single characters.</para></listitem><listitem><para>The plus -- + -- matches one or more of the previous RE. It serves a role similar to the *, but does not match zero occurrences.<indexterm><primary>occurrences</primary></indexterm></para></listitem><listitem><para>Escaped &quot;curly brackets&quot; -- \{ \} -- indicate the number of occurrences of a preceding RE to match.<indexterm><primary>match</primary></indexterm> It is necessary to escape the curly brackets since they have only their literal character meaning otherwise. </para><screen><![CDATA["[0-9]\{5\}" matches exactly five digits (characters in the range of 0 to 9).
]]></screen></listitem><listitem><para>Parenthesses -- ( ) -- enclose groups of REs. They are useful with the following &quot;|&quot; operator and in substring extraction<indexterm><primary>extraction</primary></indexterm> using expr.</para></listitem><listitem><para>The -- | -- &quot;or&quot; RE operator matches any of a set of alternate characters.</para></listitem></itemizedlist><para>What does the above tell us when we encounter a cryptic mod_rewrite directive that looks like the following?</para><screen><![CDATA[RewriteEngine on
]]><![CDATA[RewriteRule ^page1\.html$ page2.html [R=301,L]
]]></screen><para>Of course, the first line is easy: mod_rewrite is not enabled by default, so this line starts the &ldquo;Rewrite Engine<indexterm><primary>Engine</primary></indexterm>&rdquo;. The second directive is a &ldquo;Rewrite Rule<indexterm><primary>Rule</primary></indexterm>&rdquo; that instructs mod_rewrite to translate whatever URL is matched by the regular expression &ldquo;^page1\.html$&rdquo; to &ldquo;page2.html&rdquo;. </para><para>What URLs does the regular expression &ldquo;^page1\.html$&rdquo; match?<indexterm><primary>match</primary></indexterm> </para><para>In this example, adapted from <ulink url="http://www.webmasterworld.com/forum92/82.htm">An Introduction to Redirecting URLs on an Apache Server</ulink>, we have a caret at the beginning of the pattern,<indexterm><primary>pattern</primary></indexterm> and a dollar sign at the end. These are regex special characters called anchors.<indexterm><primary>anchors</primary></indexterm> The caret tells regex to begin looking for a match with the character that immediately follows it, in this case a &quot;p&quot;. The dollar sign anchor tells regex that this is the end of the string we want to match.<indexterm><primary>match</primary></indexterm> In our simple example, &quot;page1\.html&quot; and &quot;^page1\.html$&quot; are interchangable expressions and match the same string. However, &quot;page1\.html&quot; matches any string containing &quot;page1.html&quot; (apage1.html for example) anywhere in the URL,<indexterm><primary>URL</primary></indexterm> but &quot;^page1\.html$&quot; matches only a string which is exactly equal to &quot;page1.html&quot;. In a more complex redirect,<indexterm><primary>redirect</primary></indexterm> anchors (and other special regex characters) are often essential.</para><para>Putting all the above together, we can see that &ldquo;^page1\.html$&rdquo; matches URLs that start (the caret -- ^ --) with &ldquo;page1&rdquo;, immediately followed by a literal dot (escaped dot --\.--, as opposed to a simple tot, which is a metacharacter that matches any single character except newline), immediately followed by &ldquo;html&rdquo; and the end of the URL (dollar sign --$--).</para><para>In our example, we also have an &quot;[R=301,L]&quot;. These are called flags in mod_rewrite and they're optional parameters. &quot;R=301&quot; instructs Apache to return a 301 status code with the delivered page and, when not included as in [R,L], defaults to 302. The &quot;L&quot; flag tells Apache that this is the last rule that it needs to process, IF the RewriteRule pattern is matched. Experts suggest that you get in the habit of including the &quot;L&quot; flag with every RewriteRule to avoid unpleasant surprises.</para><para>One powerful option in creating search patterns is specifying that a subexpression that was matched earlier in a regular expression is matched again later in the expression. We do this using backreferences.<indexterm><primary>backreferences</primary></indexterm> Backreferences are named by the numbers 1 through 9, preceded by the backslash/escape character when used in this manner (in mod_rewrite,<indexterm><primary>rewrite</primary></indexterm> you have to use the dollar sign instead of the backslash, but in <acronym>PHP</acronym> you will use the backslash<indexterm><primary>backslash</primary></indexterm>, so don't get confused, it just depends on the context the regular expression is in). These backreferences refer to each successive group in the match pattern,<indexterm><primary>pattern</primary></indexterm> as in /(one)(two)(three)/\1\2\3/ (or $1, $2 and $3 for mod_rewrite). Each numbered backreference refers to the group that has the word corresponding to the number.</para><para>Thus the following URL translation:<indexterm><primary>translation</primary></indexterm></para><screen><![CDATA[#Your Account
]]><![CDATA[RewriteRule ^userinfo-([a-zA-Z0-9_-]*)\.html
]]><![CDATA[modules.php?name=Your_Account&op=userinfo&username=$1
]]></screen><para>in the .htaccess file (<xref linkend="htaccess-file">) will match any URL that starts (carret --^--) with &ldquo;userinfo-&rdquo;, immediately followed by any number (star --*--) of characters belonging to the alphanumeric class (a-z, A-Z,<indexterm><primary>A-Z</primary></indexterm> 0-9), including underscores (_) and dashes (-), followed by a literal dot (an escaped dot --\.--) and &ldquo;html&rdquo;. The Rewrite Rule instructs mod_rewrite to translate ther URL to </para><screen><![CDATA[modules.php?name=Your_Account&op=userinfo&username=$1
]]></screen><para>where $1 is a backreference, referring to the first matched subexpression,<indexterm><primary>subexpression</primary></indexterm> the one inside the parenthesses (). Since inside the parenthesses is a regular expression that matches &ldquo;any number of characters belonging to the alphanumeric class,<indexterm><primary>class</primary></indexterm> including underscores and dashes<indexterm><primary>dashes</primary></indexterm>&rdquo;, $1 will contain whatever alphanumeric characters were between &ldquo;userinfo-&rdquo; and &ldquo;.html&rdquo; (including underscores and dashes). In PHP-Nuke, this is the username, so that the URL returned by mod_rewrite<indexterm><primary>rewrite</primary></indexterm> will be</para><screen><![CDATA[modules.php?name=Your_Account&op=userinfo&username=(some matched username)
]]></screen><para>thus completing the transformation of a static URL (that <application>PHP-Nuke</application> does not understand), to a dynamic one that makes perfectly sense to <application>PHP-Nuke</application> (see <xref linkend="GoogleTap-how-it-works"> for the complete picture).</para></sect1>
<sect1 id="htaccess-file"><title>The .htaccess file</title><para>An .htaccess file just is a plain text file that contains web server &ldquo;directives<indexterm><primary>directives</primary></indexterm>&rdquo; (another word for instructions in the Apache world), one per line. Think of it as an .ini file for your web server.<indexterm><primary>server</primary></indexterm> The peculiarity of the .htaccess files is that, contrary to .ini files, their directives can be overwritten by .htaccess files located in subdirectories.<indexterm><primary>subdirectories</primary></indexterm> </para><para>Thus your web server root directory may contain an .htaccess file (perhaps put in place by your ISP) whose directives should be valid through the whole website.<indexterm><primary>website</primary></indexterm> However, you can create separate .htaccess files, one for each subdirectory<indexterm><primary>subdirectory</primary></indexterm> of your website,<indexterm><primary>website</primary></indexterm> containing directives that override those of the root. In this manner, you can achieve a very fine-grained control of the web server's behaviour.</para><warning>
<title>
Beware of hidden .htaccess files!
</title>
<para>
Just because you don't see any .htaccess file there, does not necessarily mean there isn't one! Some hosts will hide files whose names start with a period, so you'd better ask your ISP. Overwriting an .htaccess file can affect your website in a very negative way - you could even lose access to it, if you delete an .htaccess file that contained directives vital to your configuration.
</para>
</warning>
<para>If you don't have access to the web server configuration file (a usual situation in mass hosting environments), then a properly populated .htaccess file is your only way of setting server configuration options. Apart form URL manipulation, there is a whole bunch of interesting things you can achieve with the .htaccess file, see <xref linkend="make-PHP-Nuke-hot-link-stealth">, <xref linkend="make-dynamic-CSS">, or <xref linkend="change-PHP-parameters">, for example. But before you do them, please make a backup of the existing .htaccess file!</para><para>Also bear in mind that, if you have full control of your server (i.e. administrator access to its configuration file), then it will be way faster to avoid using .htaccess and insert all the necessary lines in the configuration<indexterm><primary>configuration</primary></indexterm> file itself. As the <ulink url="http://httpd.apache.org/docs/howto/htaccess.html#when">Apache HOWTO on when (not) to use .htaccess files</ulink> says, in general, use of .htaccess files should be avoided when possible. Any configuration that you would consider putting in a .htaccess file, can just as effectively be made in a &lt;Directory&gt; section in your main server<indexterm><primary>server</primary></indexterm> configuration file.</para><para>There are two main reasons to avoid the use of .htaccess files:</para><orderedlist><listitem><para><indexterm><primary>Enumerate</primary></indexterm>The first of these is performance.<indexterm><primary>performance</primary></indexterm> When AllowOverride is set to allow the use of .htaccess files, Apache will look in every directory for .htaccess files. Thus, permitting .htaccess files causes a performance hit, whether or not you actually even use them! Also, the .htaccess file is loaded every time a document is requested.</para><para>Further note that Apache must look for .htaccess files in all higher-level<indexterm><primary>higher-level</primary></indexterm> directories, in order to have a full complement of directives that it must apply. Thus, if a file is requested out of a directory /www/htdocs/example, Apache<indexterm><primary>Apache</primary></indexterm> must look for the following files:</para><screen><![CDATA[/.htaccess
]]><![CDATA[/www/.htaccess
]]><![CDATA[/www/htdocs/.htaccess
]]><![CDATA[/www/htdocs/example/.htaccess
]]></screen><para>And so, for each file access out of that directory, there are 4 additional file-system accesses, even if none of those files are present. (Note that this would only be the case if .htaccess files were enabled for /, which is not usually the case.<indexterm><primary>case</primary></indexterm>)</para></listitem><listitem><para><indexterm><primary>Enumerate</primary></indexterm>The second consideration is one of security.<indexterm><primary>security</primary></indexterm> You are permitting users to modify server configuration,<indexterm><primary>configuration</primary></indexterm> which may result in changes over which you have no control.<indexterm><primary>control</primary></indexterm> Carefully consider whether you want to give your users this privilege.</para></listitem></orderedlist><para>Note that it is completely equivalent to put a .htaccess file in a directory /www/htdocs/example containing a directive, and to put that same directive in a Directory section &lt;Directory /www/htdocs/example&gt; in your main server<indexterm><primary>server</primary></indexterm> configuration:<indexterm><primary>configuration</primary></indexterm></para><para>.htaccess file in /www/htdocs/example:</para><screen><![CDATA[AddType text/example .exm
]]></screen><para>httpd.conf example:</para><screen><![CDATA[<Directory /www/htdocs/example>
]]><![CDATA[AddType text/example .exm
]]><![CDATA[</Directory>
]]></screen><para>However, putting this configuration in your server configuration file will result in less of a performance hit, as the configuration is loaded once when Apache starts, rather than every time a file is requested. Remember this, before you complain that Googletap (<xref linkend="GoogleTap">) is too slow for you.</para><tip>
<title>
How to disable .htaccess completely
</title>
<para>
The use of .htaccess files can be disabled completely by setting the AllowOverride directive to "none"
</para>
<screen>
<![CDATA[
AllowOverride None
]]>
</screen>
</tip>
<para>In the sections to follow, we will see that the .htaccess file has to be populated with lines like</para><screen><![CDATA[#Your Account
]]><![CDATA[RewriteRule ^userinfo-([a-zA-Z0-9_-]*)\.html
]]><![CDATA[modules.php?name=Your_Account&op=userinfo&username=$1
]]></screen><para>If you don't use the .htaccess file for performance reasons, you should put those lines in the configuration file. It is these lines that trigger mod_rewrite (<xref linkend="mod-rewrite">) to translate static URLs that match the regular expression (<xref linkend="regular-expressions">)</para><screen><![CDATA[^userinfo-([a-zA-Z0-9_-]*)\.html
]]></screen><para>to a dynamic URL that <application>PHP-Nuke</application> understands:</para><screen><![CDATA[modules.php?name=Your_Account&op=userinfo&username=(some username)
]]></screen></sect1>
<sect1 id="make-php-nuke-search-engine-friendly"><title>How to make <application>PHP-Nuke</application> search engine friendly</title><para>To create a search engine friendly <application>PHP-Nuke</application> site, you need a means of converting dynamic URLs to static ones. How can this be done? For example, you could convert </para><screen><![CDATA[http://www.yourdomain.com/modules.php?name=Your_Account&op=userinfo&username=chris
]]></screen><para>to </para><screen><![CDATA[http://www.yourdomain.com/userinfo-chris.html
]]></screen><para>Notice that the spider-friendly format contains no indication that there are any parameters being passed at all. Rather, it simply looks like we are trying to access the file userinfo-chris.html on www.yourdomain.com, and this will not present any problems to the search<indexterm><primary>search</primary></indexterm> engine spiders.<indexterm><primary>spiders</primary></indexterm> We have of course to track this case down and use such a &ldquo;file&rdquo; accordingly, i.e split it internally into its parts, determine the parameter-value pairs and the name of the script to execute and pass the parameters (name=Your_Account, op=edituser, username=chris) to that script (modules.<indexterm><primary>modules</primary></indexterm>php) for execution. </para><para>We will describe GoogleTap,<indexterm><primary>GoogleTap</primary></indexterm> an ingenious solution to this problem, that combines the components we saw in the previous sections:</para><itemizedlist><listitem><para>mod_rewrite (<xref linkend="mod-rewrite">),</para></listitem><listitem><para>regular expressions (<xref linkend="regular-expressions">),</para></listitem><listitem><para>.htacces file (<xref linkend="htaccess-file">).</para></listitem></itemizedlist><warning>
<title>
Frontpage extensions will not work!
</title>
<para>
This does not need to upset you, since <application>PHP-Nuke</application> does not use Frontpage extensions. But for the sake of completeness, be warned that if you use Frontpage extensions, mod_rewrite will not work! Of course, if your ISP has installed them, but you don't use them, you also don't need to worry.
</para>
</warning>
<sect2 id="GoogleTap"><title>GoogleTap</title><para><ulink url="http://www.nukecops.com/postt362.html">GoogleTap</ulink> is a collection of files (header.<indexterm><primary>header</primary></indexterm>php, footer.php, .htaccess and replacements for some modules and blocks) that combines the power of regular expressions (<xref linkend="regular-expressions">) and mod_rewrite (<xref linkend="mod-rewrite">) into a <application>PHP-Nuke</application> setting, to implement a search engine friendly <application>PHP-Nuke</application> using URL manipulation. It grew out of attempts to make <application>PHP-Nuke</application> search engine friendly, that date<indexterm><primary>date</primary></indexterm> back to the 5.x versions (see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=9201">Mod_rewrite and Nuke</ulink>, <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=16544">PHP Nuke & mod_rewrite</ulink> and <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=13625">Google mod_rewrite fix</ulink>), which in turn seem to be related to similar efforts in the PostNuke camp (see <ulink url="http://news.postnuke.com/modules.php?op=modload&amp;name=News&amp;file=article&amp;sid=1804">Search engine friendly URLs revisited</ulink> and <ulink url="http://www.aquanuke.com/article358.html">Hackin' the core - Mod_Rewrite</ulink>).</para><para>Our treatment of GoogleTap is divided in three parts:</para><itemizedlist><listitem><para>Requirements (<xref linkend="GoogleTap-requirements">),</para></listitem><listitem><para>Installation (<xref linkend="GoogleTap-installation">),</para></listitem><listitem><para>How it works (<xref linkend="GoogleTap-how-it-works">).</para></listitem></itemizedlist><sect3 id="GoogleTap-requirements"><title>Requirements</title><para>To implement the solution of GoogleTap,<indexterm><primary>GoogleTap</primary></indexterm> your system needs to fullfil some <emphasis>software</emphasis> requirements:<indexterm><primary>requirements</primary></indexterm></para><itemizedlist><listitem><para>mod_rewrite needs to be compiled and loaded into apache (see <xref linkend="mod-rewrite"> on how you can check this).</para></listitem><listitem><para>allowoverrides need to be set to &quot;all&quot; for the directory location your site resides in. Check with your ISP (but see also <xref linkend="htaccess-file"> why this will make your web server much slower).</para></listitem><listitem><para>rewriteengine needs to be turned &quot;on&quot; in the .htaccess file (this is already done in the .htaccess file that comes with GoogleTap).</para></listitem></itemizedlist><para>But it also needs to fullfil some <emphasis>hardware</emphasis> requirements too: mod_rewrite has to check a lot of regular expressions for each page request. Regular expressions are very flexible, but can be very time consuming too, depending on their complexity.<indexterm><primary>complexity</primary></indexterm> The current implementation of GoogleTap seems to strain the <acronym>CPU</acronym> quite a bit. Depending on the hardware, your hosting scheme (&ldquo;root<indexterm><primary>root</primary></indexterm>&rdquo; , or &ldquo;virtual<indexterm><primary>virtual</primary></indexterm>&rdquo; server) and the number of HTTP requests you have to serve per second, this may make your pages prohibitively slow to load! Get the best hardware you can afford!</para><tip>
<title>
Monitor the load of your web server!
</title>
<para>
If you are on your own ("root") server, but your hardware is not up to the demands of mod_rewrite for computing power, you may find out that your web server load is approaching dwindling heights. There have been reports that a high server load affects the stability of Apache, or causes memory leaks. This may or may not be true for your version and configuration. But in case you are experiencing a high server load, the following script of Zhen-Xjell (the <ulink url="http://www.nukecops.com">nukecops</ulink> Webmaster) may turn out to be very helpful:
</para>
<screen>
<![CDATA[#!/usr/bin/perl -w]]>
<![CDATA[#use strict;]]>
<![CDATA[$|++;]]>
<![CDATA[]]>
<![CDATA[open(LOAD,"/proc/loadavg") || die "couldn't open /proc/loadavg: $!\n";]]>
<![CDATA[my @load=split(/ /,<LOAD>);]]>
<![CDATA[close(LOAD);]]>
<![CDATA[]]>
<![CDATA[if ($load[0] > 5) {]]>
<![CDATA[`/sbin/service httpd restart`;]]>
<![CDATA[}]]>
</screen>
<para>
Save it as loadavg.pl, adapt it to your case (location of the perl executable and the Apache start script) and set up a cron job to call loadavg.pl at regular time intervalls. The script monitors the server load average and restarts the server process, if it becomes too high, say, higher than 5 - see <ulink url="http://www.nukecops.com/postp68930.html">GoogleTap, mod_rewrite and SID defined</ulink>.
</para>
</tip>
</sect3>
<sect3 id="GoogleTap-installation"><title>Installation</title><warning>
<title>
Do not download the Google_Tap_Beta_0.6.5 package!
</title>
<para>
Do not download the Google_Tap_Beta_0.6.5 package! At least the .htacess file contained there, is missing some crucial lines. Besides that, you will not find any clear installation instructions and the files are probably already too old by the time you read this. Use the GT_Distro_10-22-03 package, or a newer one, instead! Please understand that this is beta software and still under constant development.
</para>
</warning>
<para>We will describe the manual installation of GoogleTap,<indexterm><primary>GoogleTap</primary></indexterm> as applies to the <ulink url="http://www.audioslaved.com/GT_Distro_10-22-03.zip">GT Distro 10-22-03</ulink> package (see <ulink url="http://www.nukecops.com/posts12457-0.html">Updated Google Tap Distribution 10-22-2003</ulink>):</para><itemizedlist><listitem><para>Open your header.<indexterm><primary>header</primary></indexterm>php file and make the required changes as indicated in header.<indexterm><primary>header</primary></indexterm>php_manualchanges.txt. Please use the included header.<indexterm><primary>header</primary></indexterm>php as a reference. This means that you have to find the lines:</para><screen><![CDATA[if (eregi("header.php",$_SERVER['PHP_SELF'])) {
]]><![CDATA[ Header("Location: index.php");
]]><![CDATA[ die();
]]><![CDATA[}
]]></screen><para>in your existing header.<indexterm><primary>header</primary></indexterm>php file and add </para><screen><![CDATA[ob_start();
]]><![CDATA[function replace_for_mod_rewrite(&$s) {
]]><![CDATA[$urlin = array(
]]><![CDATA["'(?<!/)modules.php\?name=News&amp;file=article&amp;
]]><![CDATA[sid=([0-9]*)&amp;mode=([a-z]*)&amp;order=([0-9]*)&amp;thold=([0-9]*)
]]><![CDATA['",
]]><![CDATA["'(?<!/)modules.php\?name=News&amp;file=article&amp;sid=([0-9]*)'",
]]><![CDATA["'(?<!/)modules.php\?name=News&file=article&sid=([0-9]*)'",
]]><![CDATA["'(?<!/)modules.php\?name=News&amp;new_topic=([0-9]*)'",
]]><![CDATA[...
]]><![CDATA[);
]]><![CDATA[
]]><![CDATA[$urlout = array(
]]><![CDATA["article-\\1-\\2-\\3-\\4.html",
]]><![CDATA["article\\1.html",
]]><![CDATA["article\\1.html",
]]><![CDATA["article-topic-\\1.html",
]]><![CDATA["archive-\\1-\\2-\\3.html",
]]><![CDATA["archive.html",
]]><![CDATA[...
]]><![CDATA[);
]]><![CDATA[$s = preg_replace($urlin, $urlout, $s);
]]><![CDATA[return $s;
]]><![CDATA[}
]]></screen><para>The code shown here has been abbreviated for clarity - please refer to the original instructions in header.<indexterm><primary>header</primary></indexterm>php_manualchanges.txt! You should leave the code of your original header.<indexterm><primary>header</primary></indexterm>php untouched, after the above lines. The final header.<indexterm><primary>header</primary></indexterm>php would look as the header.<indexterm><primary>header</primary></indexterm>php file that is included in the GT_Distro_10-22-03 package for your reference.</para><para>What you basically do with this in your header.<indexterm><primary>header</primary></indexterm>php, is start output buffering and include a function (replace_for_mod_rewrite) with two arrays, urlin<indexterm><primary>urlin</primary></indexterm> and urlout.<indexterm><primary>urlout</primary></indexterm></para></listitem><listitem><para>Open your footer.php file and make the required changes as indicated in footer.php<indexterm><primary>footer.php</primary></indexterm>_manualchanges.txt. Please use the included footer.<indexterm><primary>footer</primary></indexterm>php as a reference. This means that you have to add</para><screen><![CDATA[//Google Tap Footer Entry
]]><![CDATA[$contents = ob_get_contents(); // store buffer in $contents
]]><![CDATA[ob_end_clean(); // delete output buffer and stop buffering
]]><![CDATA[echo replace_for_mod_rewrite($contents); //display modified buffer to screen
]]><![CDATA[//End of Google Tap Footer
]]></screen><para>after the end of the foot function in your footer.<indexterm><primary>footer</primary></indexterm>php file. The final footer.<indexterm><primary>footer</primary></indexterm>php would look as the footer.<indexterm><primary>footer</primary></indexterm>php file that is included in the GT_Distro_10-22-03 package for your reference.</para><para>With this change, you just conclude the actions that you introduced in header.<indexterm><primary>header</primary></indexterm>php: there, you started output buffering,<indexterm><primary>buffering</primary></indexterm> here you have to store the buffer in a variable ($contents), before you stop buffering and call the new function<indexterm><primary>function</primary></indexterm> you introduced in header.<indexterm><primary>header</primary></indexterm>php, the replace_for_mod_rewrite() function, passing it the whole buffer content as argument.</para></listitem><listitem><para>Open your includes/sessions.php (Older than <application>PHP-Nuke</application> v.6.5,<indexterm><primary>6.5</primary></indexterm> this may be modules/Forums/includes) file and make the required changes as indicated in includes/sessions.php_manualchanges.txt. Please use the included sessions.php as a reference. This means that you replace </para><screen><![CDATA[ if ( !empty($SID) && !eregi('sid=', $url) )
]]><![CDATA[ {
]]><![CDATA[ $url .= ( ( strpos($url, '?') != false ) ?
]]><![CDATA[( ( $non_html_amp) ? '&' : '&amp;' ) : '?' ) . $SID;
]]><![CDATA[ }
]]><![CDATA[ return($url);
]]></screen><para>with </para><screen><![CDATA[ if( !empty($SID) && !eregi('sid=', $url) && !areyouabot() )
]]><![CDATA[ {
]]><![CDATA[ $url .= ( ( strpos($url, "?") != false ) ?
]]><![CDATA[( ( $non_html_amp ) ? "&" : "&amp;" ) : "?" ) . $SID;
]]><![CDATA[ }
]]><![CDATA[ return($url);
]]></screen><para>This introduces an extra check with the areyouabot() function.<indexterm><primary>function</primary></indexterm> The session <acronym>ID</acronym> ($SID) is appended to the URL ($url) only if the areyouabot() function returns false. Already from the name, we can deduce that areyouabot() checks if the visitor<indexterm><primary>visitor</primary></indexterm> is a search engine spider bot. Thus, the session <acronym>ID</acronym> will not be output on the URL that search engines get to see when they visit the site.</para><para>Of course, we still have to insert the code for the areyouabot() function.<indexterm><primary>function</primary></indexterm> We can do this after the append_sid function of sessions.php,<indexterm><primary>sessions.php</primary></indexterm> by including the code as shown in includes/sessions.php_manualchanges.txt:</para><screen><![CDATA[function areyouabot()
]]><![CDATA[{
]]><![CDATA[global $HTTP_SERVER_VARS;
]]><![CDATA[ $RobotsList = array (
]]><![CDATA[ "antibot",
]]><![CDATA[ "appie",
]]><![CDATA[ "architext",
]]><![CDATA[ "bjaaland",
]]><![CDATA[ "digout4u",
]]><![CDATA[ "echo",
]]><![CDATA[ "fast-webcrawler",
]]><![CDATA[ "ferret",
]]><![CDATA[...
]]><![CDATA[ );
]]><![CDATA[ $botID = strtolower($HTTP_SERVER_VARS['HTTP_USER_AGENT']);
]]><![CDATA[ for ($i = 0; $i < count($RobotsList); $i++)
]]><![CDATA[ {
]]><![CDATA[ if ( strstr($botID, $RobotsList[$i]) )
]]><![CDATA[ {
]]><![CDATA[ return TRUE;
]]><![CDATA[ }
]]><![CDATA[ }
]]><![CDATA[ return FALSE;
]]><![CDATA[}
]]></screen><para>Please note that the above code has been abbreviated for clarity. Refer to includes/sessions.php_manualchanges.txt for the full code of areyouabot(). The final sessions.php would look as the includes/sessions.php file that is included in the GT_Distro_10-22-03 package for your reference.</para></listitem></itemizedlist><screen><![CDATA[
]]></screen><itemizedlist><listitem><para>Upload the distribution .htaccess to your <application>PHP-Nuke</application> root directory. This is the same directory that the header.<indexterm><primary>header</primary></indexterm>php and footer.php are located within.</para></listitem></itemizedlist><caution>
<title>
Make a backup of your original .htaccess file!
</title>
<para>
Your ISP may already have set up an .htaccess file for you. Even if you don't see one there, there might be one, as some systems will not show hidden files (such as .htaccess). Check very thoroughly that you don't overwrite an existing .htaccess file with important directives that are vital to your site. If you find one, make a backup copy of it and be sure that you have saved it somewhere in a safe and accessible place. If your site breaks and you can't access it with your browser anymore, you should still be able to upload the backup copy of your .htaccess and restore the previous settings.
</para>
</caution>
<para>In order for GT to work correctly with all modules currently supported, you will need to make a few minor adjustments to the following modules:<indexterm><primary>modules</primary></indexterm></para><itemizedlist><listitem><para>Sections<indexterm><primary>Sections</primary></indexterm></para></listitem><listitem><para>Statistics<indexterm><primary>Statistics</primary></indexterm></para></listitem><listitem><para>Web_Links<indexterm><primary>Web_Links</primary></indexterm></para></listitem><listitem><para>Top</para></listitem><listitem><para>Your_Account<indexterm><primary>Your_Account</primary></indexterm></para></listitem></itemizedlist><para>You can either overwrite your existing file with the one included in the distribution or make the manual changes as indicated in the readme files contained within each module.<indexterm><primary>module</primary></indexterm> (Make sure you backup your existing files first! Included files are based on the ones located at cvs.nukecops.<indexterm><primary>nukecops</primary></indexterm>com). </para><para>The changes correct some links in the above modules.<indexterm><primary>modules</primary></indexterm> If you check, you will see that the corrections are really minimal, but are nonetheless essential for a correct working of the GoogleTap:<indexterm><primary>GoogleTap</primary></indexterm> they replace the ampersand (&amp;) on the links, with its equivalent &ldquo;HTML entity<indexterm><primary>entity</primary></indexterm>&rdquo; (&amp;amp;) (but not in the language files, where the changes work in the opposite direction, replacing &amp;amp; with &amp;). </para><para>This is actually an ommission on the part of the modules,<indexterm><primary>modules</primary></indexterm> that GoogleTap is just trying to correct: to be HTML 4.x compliant, you can't put an ampersand<indexterm><primary>ampersand</primary></indexterm> (&amp;) on the URL,<indexterm><primary>URL</primary></indexterm> you have to put its <ulink url="http://www.bbsinc.com/symbol.html">HTML entity</ulink> (&amp;amp;) instead. This may not harm your links in most situations if you don't do it, but if you pass the URL through some regular expression, as GoogleTap does through mod_rewrite (see <xref linkend="GoogleTap-how-it-works"> for an explanation of how GoogleTap works)), you have to know if the ampersand<indexterm><primary>ampersand</primary></indexterm> is meant in a literal way, or if it is a <emphasis>metacharacter<indexterm><primary>character</primary></indexterm></emphasis> of some regular expression (a character that is not a &ldquo;literal&rdquo; , i.e. does not match (only) itself ).</para><para>You can now upload the GT (Google Tap) converted blocks - currently supported are:</para><itemizedlist><listitem><para>Scrolling Forums Block<indexterm><primary>lock</primary></indexterm></para></listitem><listitem><para>Top 10 Downloads Block<indexterm><primary>lock</primary></indexterm></para></listitem><listitem><para>Top 10 Web_Links Block<indexterm><primary>lock</primary></indexterm></para></listitem><listitem><para>Sections Articles Block<indexterm><primary>lock</primary></indexterm></para></listitem></itemizedlist><para>To install, simply overwrite your existing block.<indexterm><primary>block</primary></indexterm> Make sure they are enabled in the blocks administration panel.<indexterm><primary>panel</primary></indexterm></para></sect3>
<sect3 id="GoogleTap-how-it-works"><title>How it works</title><para>The GoogleTap works as follows:</para><para>The header.<indexterm><primary>header</primary></indexterm>php file starts output buffering. This delays the output - all contents are temporarily sent to an internal buffer.<indexterm><primary>buffer</primary></indexterm> It also defines a function,<indexterm><primary>function</primary></indexterm> replace_for_mod_rewrite(). This function takes a sole argument (a variable) and replaces every occurence of a member of the urlin array with the respective member of the urlout<indexterm><primary>urlout</primary></indexterm> array (we have seen the urlin and urlout arrays already in <xref linkend="GoogleTap-installation">). You can view the urlin and urlout arrays as ordered collections of regular expressions (see <xref linkend="regular-expressions">), where the first member of urlin corresponds to the first member of urlout,<indexterm><primary>urlout</primary></indexterm> the second member of urlin to the second member of urlout and so forth. </para><para>The replace_for_mod_rewrite() function examines the contents of the variable that was passed to it as argument (remember that in <acronym>PHP</acronym> a variable can hold the contents of a whole page - in fact, in our case,<indexterm><primary>case</primary></indexterm> it does exactly that!) and replaces every occurence of the first regular expression in urlin, with the first element of urlout.<indexterm><primary>urlout</primary></indexterm> It does so with all other regular expressions of urlin - if it finds a string that matches the nth regular expression, it replaces that string with the nth array member of urlout.<indexterm><primary>urlout</primary></indexterm> The first five replacement pairs<footnote><para>For better readability, the urlin regular expression was broken across several lines in their table cell. The parts of the regular expression that match an URL parameter of the dynamic URL are on separate lines. But in reality, the regular expression is a one line long string. </para></footnote> are shown in <xref linkend="tab-urlin-urlout">.</para><para><table id="tab-urlin-urlout"><title>URL replacement with replace_for_mod_rewrite(): dynamic to static.</title><tgroup cols="2" colsep="1" rowsep="1">
<colspec colname="col0" align="left">
<colspec colname="col1" align="left">
<tbody>
<row>
<entry align="left" valign="top"><para>urlin: regular expression for dynamic URL</para></entry>
<entry align="left" valign="top"><para>urlout: corresponding static URL</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>'(?&lt;!/)modules.php\?name=News</para><para>&amp;amp;file=article</para><para>&amp;amp;sid=([0-9]*)</para><para>&amp;amp;mode=([a-z]*)</para><para>&amp;amp;order=([0-9]*)</para><para>&amp;amp;thold=([0-9]*)'</para></entry>
<entry align="left" valign="top"><para>article-\\1-\\2-\\3-\\4.html</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>'(?&lt;!/)modules.php\?name=News</para><para>&amp;amp;file=article</para><para>&amp;amp;sid=([0-9]*)'</para></entry>
<entry align="left" valign="top"><para>article\\1.html</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>'(?&lt;!/)modules.php\?name=News</para><para>&amp;file=article</para><para>&amp;sid=([0-9]*)'</para></entry>
<entry align="left" valign="top"><para>article\\1.html</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>'(?&lt;!/)modules.php\?name=News</para><para>&amp;amp;new_topic=([0-9]*)'</para></entry>
<entry align="left" valign="top"><para>article-topic-\\1.html</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>'(?&lt;!/)modules.php\?name=Stories_Archive</para><para>&amp;sa=show_month</para><para>&amp;year=([0-9]*)</para><para>&amp;month=([0-9]*)</para><para>&amp;month_l=([a-zA-Z]*)'</para></entry>
<entry align="left" valign="top"><para>archive-\\1-\\2-\\3.html</para></entry>
</row>
</tbody>
</tgroup></table></para><para>From <xref linkend="tab-urlin-urlout"> we can already see that an URL of the form</para><screen><![CDATA[(something)modules.php?name=News&amp;file=article&amp;sid=(some SID)
]]><![CDATA[&amp;mode=(some mode)&amp;order=(some order)&amp;thold=(something)
]]></screen><para>is replaced with </para><screen><![CDATA[article-(some SID)-(some mode)-(some order)-(something.html
]]></screen><para>(first replacement pair of the table), while an URL of the form</para><screen><![CDATA[(something)modules.php?name=News&amp;file=article&amp;sid=(someSID)
]]></screen><para>is replaced with</para><screen><![CDATA[article(some SID).html
]]></screen><para>(the escaped numbers in the second column of <xref linkend="tab-urlin-urlout"> represent &quot;backreferences&quot;<indexterm><primary>backreferences</primary></indexterm>: they match the subexpressions inside the () of the expressions in the first column. \1 matches the first subexpression,<indexterm><primary>subexpression</primary></indexterm> \2 the second and so forth).</para><para>Some explanations on the regular expressions used in the urlin column of <xref linkend="tab-urlin-urlout"> (see also <xref linkend="regular-expressions">):</para><itemizedlist><listitem><para>(?&lt;!/) is a so-called assertion.<indexterm><primary>assertion</primary></indexterm> It means that this pattern will only be valid, if it does not start with a preceding slash and helps us convert only links inside our <application>PHP-Nuke</application> site (so links to external sites will not be converted). </para></listitem><listitem><para>The question mark on the URL must be escaped, so we have to write \? to match it.</para></listitem><listitem><para>The ampersands (&amp;) on the URL must be in the form of their HTML entities,<indexterm><primary>entities</primary></indexterm> &ldquo;&amp;amp;&rdquo; (see <ulink url="http://www.ncbi.nlm.nih.gov/entrez/query/static/entities.html">SGML entities</ulink>). That's why all affected modules will have to be changed to echo URLs that contain &amp;amp; instead of &amp; (this was done in <xref linkend="GoogleTap-installation">).</para></listitem><listitem><para>sid=([0-9]*) indicates that you may have any digit from 0 to 9 after sid=. The * means that the occurrence may be 0 or more times. </para></listitem><listitem><para>mode=([a-zA-Z]*) indicates that you may have any alphabetical character<indexterm><primary>character</primary></indexterm> after mode=. Again, the * means that the occurence may be 0 or more times.</para></listitem><listitem><para>The parenthesis () around a regular expression like [a-zA-Z]* or [0-9]* indicate that this is a subexpression that, if matched, will be stored in an internal numbered buffer that we cann access as \1, \2, \3 and so forth. Thus, if sid=([0-9]*) is the first such subexpression in an URL,<indexterm><primary>URL</primary></indexterm> \1 will internally store the sid value, whatever it is, as long as it is matched by [0-9]* , which matches arbitrarily long sequences of digits.<indexterm><primary>digits</primary></indexterm> If it is the second one, then the session <acronym>ID</acronym> will be stored in \2.</para></listitem><listitem><para>The matched subexpressions (\1, \2, \3 etc) are then used in the regular expressions of the urlout array to construct a simpler, static looking URL that nevertheless contains all necessary information to convert it back to the dynamic version (this backward conversion is carried up in the .htaccess file, see below).</para></listitem></itemizedlist><para>The replace_for_mod_rewrite() function is not called in header.<indexterm><primary>header</primary></indexterm>php though - it is only defined there. As its name says, header.<indexterm><primary>header</primary></indexterm>php outputs the <emphasis>standard</emphasis> <application>PHP-Nuke</application> header (as opposed to the custom HTML header,<indexterm><primary>header</primary></indexterm> which is contained in includes/my_heder.php, see <xref linkend="modifying-php-nuke-html-header">). It would be too early to call replace_for_mod_rewrite() during header generation. Instead, everything is meticulously gathered in the &ldquo;output buffer<indexterm><primary>buffer</primary></indexterm>&rdquo; of <acronym>PHP</acronym> (to learn more about output buffering in PHP,<indexterm><primary>PHP</primary></indexterm> see <ulink url="http://www.devshed.com/Server_Side/PHP/OutputBuffering/page1.html">Output Buffering With PHP</ulink> and the <ulink url="http://www.php.net/manual/en/ref.outcontrol.php">PHP manual pages on output control functions</ulink>).</para><para>As <application>PHP-Nuke</application> outputs the page contents (which continue to land in the output buffer), it eventually reaches the page footer.<indexterm><primary>footer</primary></indexterm> This is the job of footer.php.<indexterm><primary>footer.php</primary></indexterm> We already saw in <xref linkend="GoogleTap-installation"> that it is the footer who calls replace_for_mod_rewrite(): it stops buffering,<indexterm><primary>buffering</primary></indexterm> saves the buffer contents in a variable, cleans up the buffer and calls replace_for_mod_rewrite(). </para><para>What are the contents of the output buffer at this stage? You guessed -it - the whole page, all the HTML that comprises the &ldquo;page source&rdquo; (the HTML code you see when you hit the &ldquo;View source&rdquo; menu entry of your browser. Without GoogleTap,<indexterm><primary>GoogleTap</primary></indexterm> this would be the HTML code that would be sent to your browser to render the page, with all its text and links and...</para><para>Huh! Did I say links? What if your page contains dynamic links? In fact, it is very unusual for a <application>PHP-Nuke</application> page to NOT contain any dynamic links. Dont't they have to be replaced with their static pendants too? Of course they do! Thus, it should be clear to you by now, that just by changing the URLs from dynamic to static, we are by far not done - we have to do this for every URL contained in the HTML of our page. </para><para>Well, that's exactly what that call of replace_for_mod_rewrite() in the footer does: it passes the whole page as argument to replace_for_mod_rewrite(), which then does an elaborate &ldquo;search and replace&rdquo; in the whole page, according to the urlin and urlout arrays, as indicated by <xref linkend="tab-urlin-urlout">. </para><para>This completes the translation from dynamic to static: the browser gets a page where every dynamic link of <application>PHP-Nuke</application> has been replaced by a static one. The user - and the search engine - sees only static links on the page to follow. </para><para>What's more, through the changes we did in sessions.php during installation (see <xref linkend="GoogleTap-installation">), we have already taken care that if the visitor is a search engine bot, it will not be shown the session <acronym>ID</acronym> on the URL. Normal users will continue to see it, though. With this ingenious method, we get the best of two worlds: users can rely on the security and comfort that <acronym>PHP</acronym> session management has to offer - and search engines will not be chased away from our site through some huge URLs.<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_smile.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_smile.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_smile.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_smile.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject></para>
<para>But suppose that the user (or better, the search engine,<indexterm><primary>engine</primary></indexterm> for which we are actually getting into all this trouble) now clicks on one of those static links on the page thet we previously served through our header-footer trick - what then? How are we going to tell <application>PHP-Nuke</application> which link was meant? Remember, <application>PHP-Nuke</application> sits on the server and understands only links like</para><screen><![CDATA[modules.php?name=Your_Account&amp;op=userinfo&amp;username=chris
]]></screen><para>Only so it is going to understand that you mean to see the User Info profile<indexterm><primary>profile</primary></indexterm> for chris (see <xref linkend="fig-your-info-profile">), in the Your_Account module.<indexterm><primary>module</primary></indexterm> But the user will not click on that link, because all dynamic links were already transformed to static (by replace_for_mod_rewrite()), <emphasis>before</emphasis> the page was served by the web server to his browser. The user will click on a link that looks like</para><screen><![CDATA[userinfo-chris.html
]]></screen><para>This is because, according to the urlin and urlout arrays, which control<indexterm><primary>control</primary></indexterm> dynamic-to-static translation of URLs in the replace_for_mod_rewrite() function of header.<indexterm><primary>header</primary></indexterm>php, the regular expression </para><screen><![CDATA['(?<!/)modules.php\?name=Your_Account&amp;op=userinfo&amp;username=([a-zA-Z0-9_-]*)'
]]></screen><para>is translated to</para><screen><![CDATA[userinfo-\\1.html
]]></screen><para>(the \1 in the second expression matches a subexpression, enclosed in parenthesis<indexterm><primary>parenthesis</primary></indexterm> (), of the first regular expression, in this case whatever follows the &quot;username=&quot; string).</para><para>For the reverse translation, from static to dynamic,<indexterm><primary>dynamic</primary></indexterm> the .htaccess file comes into play. It tells mod_rewrite to rewrite every URL that looks like </para><screen><![CDATA[userinfo-(some username).html
]]></screen><para>to </para><screen><![CDATA[modules.php?name=Your_Account&op=userinfo&username=(some username)
]]></screen><para>Here is the relevant part of .htaccess that is responsible for this translation:<indexterm><primary>translation</primary></indexterm></para><screen><![CDATA[#Your Account
]]><![CDATA[RewriteRule ^userinfo-([a-zA-Z0-9_-]*).html
]]><![CDATA[modules.php?name=Your_Account&op=userinfo&username=$1
]]></screen><para>You will find rewrite rules like the above, for every regular expression pair that you encounter in the urlin and urlout arrays of the header.<indexterm><primary>header</primary></indexterm>php file. Only the roles have been exchanged: the first expression is the static one, the second the dynamic.<indexterm><primary>dynamic</primary></indexterm></para><para>This way, <application>PHP-Nuke</application> never sees the static URLs - when they arrive at the <acronym>PHP</acronym> interpreter,<indexterm><primary>interpreter</primary></indexterm> they have been already translated to the original, correct, dynamic URLs that <application>PHP-Nuke</application> knows how to treat.</para><para>While it is at it, by the way, .htaccess does some other neat things for us too. They don't have to do with the search-engine friendliness,<indexterm><primary>friendliness</primary></indexterm> but rather with the security of our site, and come as a nice by-product of the mod_rewrite<indexterm><primary>rewrite</primary></indexterm> technology:</para><itemizedlist><listitem><para>It blocks access to almost everything, except .php files:</para><screen><![CDATA[<FilesMatch "\.(inc|tpl|h|ihtml|sql|ini|conf|class|bin|spd|theme|module)$">
]]><![CDATA[deny from all
]]><![CDATA[</FilesMatch>
]]></screen></listitem><listitem><para>It redirects email spammers robots to a fake page (some emailsforyou.php)</para><screen><![CDATA[RewriteCond %{HTTP_USER_AGENT} ^Alexibot [OR]
]]><![CDATA[RewriteCond %{HTTP_USER_AGENT} ^asterias [OR]
]]><![CDATA[RewriteCond %{HTTP_USER_AGENT} ^BackDoorBot [OR]
]]><![CDATA[RewriteCond %{HTTP_USER_AGENT} ^Black.Hole [OR]
]]><![CDATA[RewriteCond %{HTTP_USER_AGENT} ^BlackWidow [OR]
]]><![CDATA[...
]]><![CDATA[RewriteRule ^.*$ emailsforyou.php [L]
]]></screen></listitem></itemizedlist><para>Of course, this is only going to work for email robots that are not clever enough to fake the HTTP_USER_AGENT string they present to the server.<indexterm><primary>server</primary></indexterm></para></sect3>
</sect2>
</sect1>
<sect1 id="make-PHP-Nuke-hot-link-stealth"><title>How to make <application>PHP-Nuke</application> hot link stealth</title><para>The Web has made incorporating material from other sources almost trivial:<indexterm><primary>trivial</primary></indexterm> an anchor with the source attribute pointing to someone else's image and voila! your page looks much nicer already - thanks to the hard work of that other person, or organization. </para><para>PHP-Nuke amplifies this tendency for &ldquo;content sharing&rdquo; with its easily programmed blocks: just include the output of another page in the $content variable, perhaps utilizing the output buffer - and that's all, your block now shows the content of that page (see <xref linkend="block-creation">). Numerous blocks, such as Meteosat (<xref linkend="PHP-Nuke-Meteosat-block">), Sun &amp; Moon (<xref linkend="PHP-Nuke-Moon-Sun-block">), Daily Comic <xref linkend="PHP-Nuke-comic-block">), to name just a few, take advantage of this technology. They inform, beautify and entertain you.</para><para>Or they make somebody very angry about you! This somebody is the original author who sees his content being used without permission and the bandwidth of his site used for purposes of other sites. You should not underestimate these two problems:</para><itemizedlist><listitem><para>Copyright:<indexterm><primary>Copyright</primary></indexterm> although a block that displays sattelite images for public use may be above suspicion, the situation becomes less favourable for a block<indexterm><primary>block</primary></indexterm> that displays the work of other artists - cartoonists,<indexterm><primary>cartoonists</primary></indexterm> for example.</para></listitem><listitem><para>Bandwidth: because the image is still being called from the server of the author or his hosting account, the bandwidth or data transfer is tacked onto his account for each time that image is loaded. </para></listitem></itemizedlist><para>If you are the author of a collection of image files that you do not want to share through this so-called &ldquo;hot&rdquo; linking, there is a solution to your problem. It is not specific to PHP-Nuke, but it is based on mod_rewrite (<xref linkend="mod-rewrite">) and the .htaccess file (<xref linkend="htaccess-file">), so that if you are willing to deploy these two for a search engine friendly <application>PHP-Nuke</application> (as shown in <xref linkend="make-php-nuke-search-engine-friendly">), then why not use them for a hot link stealth <application>PHP-Nuke</application> too? Even more so, since the requirements from a programming standpoint are minimal.</para><caution>
<title>
Find out if you have mod_rewrite installed first!
</title>
<para>
Be sure that your web server supports mod_rewrite (see <xref linkend="mod-rewrite"> on how to find out).
</para>
</caution>
<para>Here is what you have to do in order to show an error to everybody who is trying to access an image on your server,<indexterm><primary>server</primary></indexterm> but is not currently viewing a page of your domain:<indexterm><primary>domain</primary></indexterm></para><para>Insert the following lines in the .htaccess file of the directory you want to protect:</para><screen>
RewriteEngine on <co id="reon">
RewriteCond %{HTTP_REFERER} !^$ <co id="rewrite1">
RewriteCond %{HTTP_REFERER} !^http://(www\.)?mydomain.com/.*$ [NC] <co id="rewrite2">
RewriteRule \.(gif|jpg)$ - [F] <co id="rewrite3">
</screen>
<calloutlist>
<callout arearefs="reon">
<para>
Enable URL rewriting through mod_rewrite.
</para>
</callout>
<callout arearefs="rewrite1">
<para>
Check that the HTTP referer of the client is not empty
</para>
</callout>
<callout arearefs="rewrite2">
<para>
Check that the HTTP referer of the client does NOT start with your domain. Of course, you must enter your real domain here. The ! at the start of the condition pattern negates the result of the pattern that follows it. ^ and $ are special characters used to match the start and the end of the string in question respectively. Thus the pattern ^http:// would match strings starting in http://. The sequence .* will match any character f or 0 or more times, and so adding it to the start or end of a particular string will allow fuzzy pattern matching. The ? will match zero or one occurences of the string that precedes it, so (www\.)? means that either "www." appears once, or not at all. The [NC] flag at the end of the RewriteCond lines tells the server to ignore the case (no case) while looking for matches.
</para>
</callout>
<callout arearefs="rewrite3">
<para>
Finally, if all conditions are met, this rewrite rule matches anything that ends in .gif or .jpg. Note that the dot in front of the file ending is escaped in the regular expression (\.) and that the OR function is indicated by the | . The dollar sign denotes the end of the URL. The [F] flag tells the browser that it is forbidden to retrieve that file.
</para>
</callout>
</calloutlist>
<note>
<title>
Will not work with faked HTTP_REFERER!
</title>
<para>
The method will also prevent web spiders from downloading your images. Web spiders are a popular tool and are used whenever a complete local copy of a site or resource is preferred over online reading. Bear in mind, however, that good spiders allow the user to fake the HTTP referer field, thus presenting themselves as coming from some internal page of your domain. There is no way to force a determined user to look at your pages or the advertisements you have there, before downloading your precious images.
</para>
</note>
<para>Of course, you can just as well redirect the offending visitor to a file you have created just for this purpose, one that contains a standard text or image that reflects your feelings.<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> For this, you can change the above slightly to:</para>
<screen><![CDATA[RewriteEngine on
]]><![CDATA[RewriteCond %{HTTP_REFERER} !^$
]]><![CDATA[RewriteCond %{HTTP_REFERER} !^http://(www\.)?mydomain.com/.*$ [NC]
]]><![CDATA[RewriteRule \.(gif|jpg)$ http://www.mydomain.com/nasty.gif [R,L]
]]></screen><important>
<title>
Don't block search engine caches, image searches and automatic translations on your site!
</title>
<para>
The rewrite conditions we use here are a bit too restrictive: everything whose referer is not in our domain is blocked or redirected. But what about image searches with search engines? A search engine will hot link our image when it shows it to the searcher. The same is true with the search engine cache and the automatic translations offered by Google or Altavista. You will not want to block these services, let alone force search engines to display a nasty image in place of figures in a cached or translated document from your site.
</para>
<para>
Thus, unless you don't care, you will have to be more thoughtful and construct additional rewrite conditions that do not block useful services. For example, the following rules will allow the Altavista and Google translation services to hot link images from your site:
<screen>
<![CDATA[RewriteCond %{HTTP_REFERER} !^http://jump.altavista.com/.*(www\.)?mydomain\.com.*$ [NC]]]>
<![CDATA[RewriteCond %{HTTP_REFERER} !^http://translate.google.com/.*(www\.)?mydomain\.com.*$ [NC]]]>
</screen>
</para>
</important>
<para>See <ulink url="http://faq.solutionscripts.com/misc/hot_linking.html">Using Mod_rewrite to block hot linked images</ulink>, <ulink url="http://www.javascriptkit.com/howto/htaccess10.shtml">Preventing hot linking of images</ulink>, <ulink url="http://www.webmasterstop.com/tutorials/prevent-hotlinking.shtml">Preventing Hotlinking with Apache mod_rewrite</ulink> and <ulink url="http://www.fuckallyall.com/article1634.html">How to be a total prick using mod_rewrite</ulink>.</para></sect1>
<sect1 id="make-dynamic-CSS"><title>How to make a dynamic CSS</title><para>A lot of people think that <acronym>PHP</acronym> can only be used to deliver dynamic HTML<indexterm><primary>HTML</primary></indexterm> pages. This is by no means the whole story! Did you know, for example, that with <acronym>PHP</acronym> you can deliver dynamic <emphasis>CSS files</emphasis>? Forget all those multiple CSS for different browsers! You can maitain one CSS file, with <acronym>PHP</acronym> code in it - and <acronym>PHP</acronym> will interpret that code and deliver the right CSS to the right browser.</para><para>Again, the .htaccess file (see <xref linkend="htaccess-file">) plays a central role here: add this line to the .htaccess file in your <application>PHP-Nuke</application> root directory:</para><screen><![CDATA[AddType application/x-httpd-php .css
]]></screen><para>This will instruct the Apache web server to parse .css files for <acronym>PHP</acronym> commands. Then add this line <emphasis>to the top</emphasis> of your CSS file:</para><screen><![CDATA[<?php Header ("Content-type: text/css");?>
]]></screen><para>This makes sure that the .css file looks like a regular CSS file to anyone that asks. If you don't return a text/css header,<indexterm><primary>header</primary></indexterm> Mozilla will refuse to include the file if the calling page has an XHTML or strict HTML doctype.</para><para>With these two changes in place, you can now use <acronym>PHP</acronym> everywhere in your CSS file. Conditional operations,<indexterm><primary>ations</primary></indexterm> function calls, and generally the whole <acronym>PHP</acronym> functionality is at your disposal!</para><para>You could for example have a link to 'printer-friendly.<indexterm><primary>printer-friendly</primary></indexterm>php' which would set a cookie (for say 10/20secs) and redirect back to the refering page. Your CSS file would then check the &ldquo;printer&rdquo; cookie and, if set, would produce a stylesheet that is more printer friendly:</para><screen><![CDATA[<?php
]]><![CDATA[if(isset($_COOKIE['printer'])) {
]]><![CDATA[?>
]]><![CDATA[/* print styles here, turn off logos,
]]><![CDATA[do in black and white or whatever */
]]><![CDATA[<?php
]]><![CDATA[} else {
]]><![CDATA[?>
]]><![CDATA[/* regular styles */
]]><![CDATA[<?php
]]><![CDATA[}
]]><![CDATA[?>
]]></screen><note>
<title>
Your browser does not notice!
</title>
<para>
Whether you use a dynamic CSS with PHP, or a static one, your browser will never notice - just as will never notice with other HTML files anyway! Why? Because all the "dynamics" take place on the server. As soon as <acronym>PHP</acronym> finishes its work with parsing the CSS file on the server, the browser gets served a CSS file that looks just about any other CSS file would do. The only difference is that this CSS is constructed on-the-fly, taking into account whatever dynamic parameters you told it to (cookies, user preferences, browser type etc.). Your browser will never notice and will cache it like any other CSS.
</para>
</note>
<para>The above is of course just an example, since CSS already caters for alternative 'print-friendly' styles using the &quot;media&quot; attribute:<indexterm><primary>attribute</primary></indexterm></para><screen><![CDATA[<LINK rel="stylesheet" type="text/css" href="/style.css">
]]><![CDATA[<LINK rel="stylesheet" type="text/css" href="/print.css" media="print">
]]></screen><para>which, on the other hand, does not seem to be completely supported by all browsers for the moment.</para><para>Another interesting application of the dynamic CSS idea, is the construction of &ldquo;theme variants<indexterm><primary>variants</primary></indexterm>&rdquo;: different colour combinations for the same theme.<indexterm><primary>theme</primary></indexterm> Following the previous lines, you could set links somewhere in your pages, that would set a cookie and redirect back to the refering page. Your CSS file would then check the &ldquo;style&rdquo; cookie and, would produce the appropriate colours (see <ulink url="http://www.webmasterworld.com/forum83/2201.htm">Server Side Scripting in CSS Files</ulink>):</para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[switch($_COOKIE['style']) {
]]><![CDATA[ case "high_contrast":
]]><![CDATA[ $bg="black";
]]><![CDATA[ $fg="white";
]]><![CDATA[ break;
]]><![CDATA[case "silly":
]]><![CDATA[ $bg="pink";
]]><![CDATA[ $fg="red";
]]><![CDATA[ break;
]]><![CDATA[default:
]]><![CDATA[ $bg="white";
]]><![CDATA[ $fg="black";
]]><![CDATA[ break;
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[?>
]]><![CDATA[
]]><![CDATA[body {
]]><![CDATA[
]]><![CDATA[background-color: <?php =$bg;?>;
]]><![CDATA[color: <?php =$fg;?>;
]]><![CDATA[
]]><![CDATA[}
]]></screen><para>The CSS file that you should modify for such actions, is the style.css file in the styles folder of your theme (see <xref linkend="topic-structure">).</para></sect1>
<sect1 id="proceed-when-MySQL-slow"><title>How to proceed when MySQL is slow</title><para>It is of course too general a complain to say &ldquo;MySQL is slow! What is wrong with my pages?&rdquo;, but nonetheless, there exist a couple of things you can check if this happens to you (see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=18393">slow page load and mysql errors</ulink>):</para><itemizedlist><listitem><para>First obvious question: did your host upgrade or make changes to MySQL?<indexterm><primary>MySQL</primary></indexterm></para></listitem><listitem><para>Second, any new or modified modules added?</para></listitem><listitem><para>Third, does your host have 'log slow queries' enabled for mysql so you can isolate which ones are causing the problems? When started with the --log-slow-queries[=file_name] option, mysqld writes a log file containing all SQL commands that took more than long_query_time seconds to execute. See <ulink url="http://www.mysql.com/doc/en/Slow_query_log.html">The Slow Query Log</ulink>.</para></listitem><listitem><para>Does this happen randomly or during certain time periods throughout the day?</para></listitem><listitem><para>Maybe you need to rebuild your indexes. To rebuild your indexes, the easiest way to do so for a MyISAM table is to use the following statement, which rebuilds the index file:</para><screen><![CDATA[mysql> REPAIR TABLE tbl_name QUICK;
]]></screen><para>If you don't have access to the MySQL prompt through a terminal, you can write a small <acronym>PHP</acronym> script that does the same. Copy the following code into a file and save it as, say, repair.php:<indexterm><primary>repair.php</primary></indexterm> </para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[require("config.php");
]]><![CDATA[$host = $dbhost;
]]><![CDATA[$database = $dbname;
]]><![CDATA[$username = $dbuname;
]]><![CDATA[$password = $dbpass;
]]><![CDATA[
]]><![CDATA[mysql_connect($host, $username, $password);
]]><![CDATA[@mysql_select_db($database);
]]><![CDATA[$res = mysql_query("repair table ".$prefix."_XXXX");
]]><![CDATA[
]]><![CDATA[if ($res) {
]]><![CDATA[ echo $res;
]]><![CDATA[} else {
]]><![CDATA[ print (mysql_error());
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[?>
]]></screen><para>Dont't forget to replace &ldquo;XXXX&rdquo; with the actual name (without the prefix!) of the table you are suspecting of causing you trouble. Read the table definitions in the nuke.sql file that came with your <application>PHP-Nuke</application> package under the sql directory (you used nuke.sql during installation to populate the database,<indexterm><primary>base</primary></indexterm> see <xref linkend="database-creation"> and <xref linkend="install-db">). </para><para>Upload repair.php to the same directory on your web server where also config.php<indexterm><primary>config.php</primary></indexterm> is in - and point your browser to it. Of course, you should delete it after you are done.</para></listitem><listitem><para>The phpBB software used for the standard Forum in PHP-Nuke, comes with a table, nuke_bbsearch_wordlist,<indexterm><primary>nuke_bbsearch_wordlist</primary></indexterm> that is used to store words that occur in forum posts.<indexterm><primary>posts</primary></indexterm> Due to the large size of your database,<indexterm><primary>base</primary></indexterm> the nuke_bbsearch_wordlist table may have grown very large. By default phpBB does not include an index for that table. Lack of an index on nuke_bbsearch_wordlist can make your forum slow down. Running the SQL command below will increase the size of the nuke_bbsearch_wordlist table (could double it), but a performance increase is expected with the index (see <ulink url="http://phpnuke.org/modules.php?name=News&amp;file=article&amp;sid=6534">How to Increase your Forums Performance</ulink>):</para><screen><![CDATA[ALTER TABLE nuke_bbsearch_wordmatch ADD INDEX post_id (post_id);
]]></screen><para>Run this during a time on your site when it is least busy. More records on that table means longer run time.</para><para>If you find that this doesn't work for you, you can remove the index with:</para><screen><![CDATA[ALTER TABLE nuke_search_wordmatch DROP INDEX post_id;
]]></screen></listitem></itemizedlist><tip>
<title>
Large Slow Query Logs
</title>
<para>
The slow query log can be used to find queries that take a long time to execute and are thus candidates for optimization . With a large log, that can become a difficult task. You can pipe the slow query log through the mysqldumpslow command to get a summary of the queries which appear in the log.
</para>
</tip>
</sect1>
</chapter>
<chapter id="solve-common-problems-php-nuke"><title>How to solve common probems with PHP-Nuke</title><para>What often inhibits the work of administrators of websites made with PHP-Nuke, are the maintenance interventions that are necessary for an optimal operation<indexterm><primary>operation</primary></indexterm> of their site. You should never consider your installation of <application>PHP-Nuke</application> &ldquo;finished&rdquo;, as correction releases that eliminate bugs,<indexterm><primary>bugs</primary></indexterm> or cover security holes (<xref linkend="security-fixes">), often follow an original release and you may also feel the need for a new module that adds a much-needed functionality.<indexterm><primary>functionality</primary></indexterm> Various everyday problems are related to these activities and in this chapter we are going to discuss the most common ones and ways to solve them:</para><itemizedlist><listitem><para>How to repair a corrupt table (<xref linkend="repair-corrupt-table">),</para></listitem><listitem><para>How to restore <application>PHP-Nuke</application> from backup (<xref linkend="restore-PHP-Nuke-from-backup">),</para></listitem><listitem><para>How to install new modules (<xref linkend="install-new-modules">),</para></listitem><listitem><para>How to install patches and correct errors (<xref linkend="install-patches-correct-errors">),</para></listitem><listitem><para>How to find all registration links (<xref linkend="find-all-registration-links">),</para></listitem><listitem><para>How to allow anonymous web link submissions (<xref linkend="allow-anonymous-web-link-submissions">),</para></listitem><listitem><para>How to disable DEBUG mode (<xref linkend="disable-DEBUG-mode">).</para></listitem></itemizedlist><sect1 id="repair-corrupt-table"><title>How to repair a corrupt table</title><epigraph>
<para>
Three things are certain: Death, taxes and lost data. Guess which has occurred.
</para>
</epigraph>
<para>Occasionally, under circumstances involving high load on the server, multiple INSERTs and UPDATEs, coupled with many SELECTs (see <xref linkend="sql-syntax"> for the syntax of SQL code), or hardware failure (oh yes...whenever possible, blame the hardware! <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject>), your database server may corrupt a table. This is something it shouldn't happen, but of course this doesn't help you if it does. According to the MySQL manual on <ulink url="http://www.mysql.com/doc/en/Corrupted_MyISAM_tables.html">Corrupted MyISAM Tables</ulink>, you can get corrupted tables if some of the following things happens:</para>
<itemizedlist><listitem><para>The mysqld process being killed in the middle of a write.</para></listitem><listitem><para>Unexpected shutdown of the computer (for example, if the computer is turned off).</para></listitem><listitem><para>A hardware error.</para></listitem><listitem><para>You are using an external program (like myisamchk) on a live table.</para></listitem><listitem><para>A software bug in the MySQL or MyISAM code.</para></listitem></itemizedlist><para>and the typical symptoms for a corrupt table are:</para><itemizedlist><listitem><para>You get the error </para><screen><![CDATA[Incorrect key file for table: '...'. Try to repair it
]]></screen><para>while selecting data from the table.</para></listitem><listitem><para>Queries don't find rows in the table or return incomplete data.<indexterm><primary>data</primary></indexterm></para></listitem></itemizedlist><para>For PHP-Nuke, a typical error is MySQL errno 145 (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=332">MySQL errno: 145 Can't open file nuke bbsearch wordmatch.MYI</ulink>):</para><screen><![CDATA[Could not insert new word matches
]]><![CDATA[DEBUG MODE
]]><![CDATA[SQL Error : 1016 Can't open file: 'nuke_bbsearch_wordmatch.MYI'. (errno: 145)
]]><![CDATA[INSERT INTO nuke_bbsearch_wordmatch (post_id, word_id, title_match)
]]><![CDATA[SELECT 4467, word_id, 0 FROM nuke_bbsearch_wordlist WHERE word_text IN ('testing')
]]><![CDATA[Line : 282
]]><![CDATA[File : /xxxx/xxxx/public_html/nuke/includes/functions_search.php
]]></screen><para>You can use the repair.php script of <xref linkend="proceed-when-MySQL-slow">, or the REPAIR TABLE command from the MySQL prompt, not only to rebuild<indexterm><primary>rebuild</primary></indexterm> indexes, but also to generally repair a broken table (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=416">Missing blocks and modules</ulink>). Normally you should never have to run the REPAIR TABLE command,<indexterm><primary>command</primary></indexterm> but if disaster strikes, you are very likely to get back all your data from a MyISAM table with it (if your tables get corrupted a lot, you should try to find the reason for this, to eliminate the need to use REPAIR TABLE, see <ulink url="http://www.mysql.com/doc/en/Crashing.html">What To Do If MySQL Keeps Crashing</ulink> and <ulink url="http://www.mysql.com/doc/en/MyISAM_table_problems.html">MyISAM Table Problems</ulink>). On the MySQL prompt, type:</para><screen><![CDATA[repair table nuke_users;
]]></screen><para>to repair the nuke_users table, for example. To only check if the table is corrupt,<indexterm><primary>corrupt</primary></indexterm> use the &ldquo;check table&rdquo; SQL command:<indexterm><primary>command</primary></indexterm></para><screen><![CDATA[check table nuke_users;
]]></screen><para>See <ulink url="http://www.mysql.com/doc/en/REPAIR_TABLE.html">REPAIR TABLE Syntax</ulink> for the syntax of REPAIR TABLE.</para><para>If you don't have a ccess to the MySQL prompt, but can access the shell,<indexterm><primary>shell</primary></indexterm> you can use the myisamchk utility.<indexterm><primary>utility</primary></indexterm> Again, you can both check and repair a table. To check it, type </para><screen><![CDATA[myisamchk /path/to/the/table
]]></screen><para>on the shell's command line. To repair it, use</para><screen><![CDATA[myisamchk -r /path/to/the/table
]]></screen><para>If you ever needed the REPAIR TABLE function of MySQL (and went through the torture process of wondering what this might do to your beloved data), then you may be appreciating backups a bit more - see <xref linkend="backup-mysql-using-browser"> and backup your database regularly!</para></sect1>
<sect1 id="restore-PHP-Nuke-from-backup"><title>How to restore <application>PHP-Nuke</application> from backup</title><para>
<figure id="fig-backup-2">
<title>
Administration panel: Backup DB.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1186;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1186;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1186;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1186;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Backup DB.</phrase>
</textobject>
<caption>
<para>Administration panel: Backup DB.</para>
</caption>
</mediaobject>
</figure>
</para><para>We have already seen that <application>PHP-Nuke</application> offers a built-in database backup function<indexterm><primary>function</primary></indexterm> in the administration panel (<xref linkend="fig-backup-db">). phpMyAdmin (<xref linkend="phpmyadmin">) also offers a very good web interface to database backups and you can even use home-made scripts that automate the backup work for you (see <xref linkend="backup-mysql-using-browser">). However, we have not yet covered the procedures necessary to <emphasis>restore<indexterm><primary>restore</primary></indexterm></emphasis> a backup made with the above procedures.</para><para>
<figure id="fig-backup-db">
<title>
Administration panel: Backup DB.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1187;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1187;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1187;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1187;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Backup DB.</phrase>
</textobject>
<caption>
<para>Administration panel: Backup DB.</para>
</caption>
</mediaobject>
</figure>
</para><para>PHP-Nuke can bee seen as a structure comprising two general elements,<indexterm><primary>elements</primary></indexterm> the files and the database.<indexterm><primary>base</primary></indexterm> The pulsing heart of our dynamic CMS is the database.<indexterm><primary>base</primary></indexterm> It is actually there where the we save all usernames,<indexterm><primary>usernames</primary></indexterm> articles, statistics and all the rest. In the files, on the other hand, we have the commands that are necessary for a functioning connection to the database,<indexterm><primary>base</primary></indexterm> the fetching and processing of the data and finally their saving back to the database again.</para><para>Although the database is experiencing constant modifications (UPDATEs) - practically every time some user is vieweing some page - the files themselves are subject to much slower change, most of the time due to necessary interventions of the administrator.<indexterm><primary>administrator</primary></indexterm> If, for example, we have <application>PHP-Nuke</application> 6.8 installed, then the possible modifications<indexterm><primary>modifications</primary></indexterm> to our installation include:</para><itemizedlist><listitem><para>Installation of a new theme we programmed ourselves, or modification of an existing theme.<indexterm><primary>theme</primary></indexterm></para></listitem><listitem><para>Installation of patches that correct errors.</para></listitem><listitem><para>Installation of new modules or of modification of existisng modules in order to get a more personalized site.</para></listitem></itemizedlist><para>As you can see, if we were to lose our <application>PHP-Nuke</application> files, a recuperation would not be something impossible, although painful and annoying. On the other hand, it would be really impossible to recuperate our database<indexterm><primary>base</primary></indexterm> data,<indexterm><primary>data</primary></indexterm> if lost, due to the fact that they may change automatically, independently of the administrator's will. For example, the update of the statistics,<indexterm><primary>statistics</primary></indexterm> a user's post in the forums, or a user registration,<indexterm><primary>registration</primary></indexterm> are all events that happen independently of the administrator's will and they all find their way to the database.<indexterm><primary>base</primary></indexterm></para><para>Hopefully, the above observations have convinced you of the necessity of database backups.<indexterm><primary>backups</primary></indexterm> We recommend you to:</para><para>Make a backup of your <application>PHP-Nuke</application> at least every time you make a change to them (although a regular backup every N days would be even better).</para><para>Make a database backup as often as possible. The backup frequency should be directly proportional to the number of visits that your site attracts per day: the more visits per day , the more new data is stored in our database each day. Also in this case,<indexterm><primary>case</primary></indexterm> a regular backup is the recommended way.</para><warning>
<title>Don't trust your ISP on making backups of your data!</title>
<para>
Do not, under any circumstances, indulge to the comforting thought that your ISP is doing database backups for you, even if he talks in his marketing brochures about "security", "crash protection" or even "backups"! If you read the Standard Terms and Conditions of your ISP carefully, you will almost certainly discover that he does not assume any responsibility for data loss, unless it was the result of gross negligence (a rare condition that you will have to prove in a court).
</para>
<para>
Even if your ISP does do backups, and runs big ads declaring so, this does not mean that he does them for you! You might discover that you have to pay an &ldquo;market fair&rdquo; hourly rate for the ISP's operator's work, if you ask his help on restoring that lost table of yours...
</para>
<para>
Thus, you'd better not rely on your ISP when it comes to backups. Do your homework and you will not regret it.
</para>
</warning>
<para>Restoring a backup is very simple. All you need to do is delete all tables contained in the <application>PHP-Nuke</application> database<indexterm><primary>base</primary></indexterm> and insert the emergecy versions in their place. You can do this through the function &ldquo;SQL query<indexterm><primary>query</primary></indexterm>&rdquo; of phpMyAdmin (see <xref linkend="phpMyAdmin-navigation-bar-SQL">). Enter the full name of the backup file in the field for &ldquo;textfile&rdquo; in <xref linkend="fig-phpmyadmin-sql-query-2">, or select &ldquo;Browse<indexterm><primary>Browse</primary></indexterm>&rdquo; and then search for it in the dialog that follows.</para><para>
<figure id="fig-phpmyadmin-sql-query-2">
<title>
phpMyAdmin: SQL query.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1188;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1188;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1188;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1188;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>phpMyAdmin: SQL query.</phrase>
</textobject>
<caption>
<para>phpMyAdmin: SQL query.</para>
</caption>
</mediaobject>
</figure>
</para><para>However, it is important that we are aware of some exceptions or particular cases that may yield themselves the above restore procedure:<indexterm><primary>procedure</primary></indexterm> </para><itemizedlist><listitem><para>How to restore a single table (see <xref linkend="restore-single-table">).</para></listitem><listitem><para>How to restore a large backup (see <xref linkend="restore-large-backup">).</para></listitem></itemizedlist><para>We will talk about these cases in the following subsections.</para><sect2 id="restore-single-table"><title>How to restore a single table</title><para>Suppose we only need to restore the nuke_users table, leaving all other tables untouched. For this we use phpMyAdmin (<xref linkend="phpmyadmin">) to selectively delete the nuke_users table. We then open our backup file with a decent text editor (see <xref linkend="editing-PHP-Nuke-files">) and copy from it only those parts that are relevant to the </para><itemizedlist><listitem><para>structure and</para></listitem><listitem><para>data </para></listitem></itemizedlist><para>of the nuke_users table. The structure part is normally preceded by a three-line comment like:</para><screen><![CDATA[#
]]><![CDATA[# Table structure for table `nuke_users`
]]><![CDATA[#
]]></screen><para>The data part, on the other hand, is preceded by a three-line comment like:</para><screen><![CDATA[#
]]><![CDATA[# Dumping data for table `nuke_users`
]]><![CDATA[#
]]><![CDATA[
]]></screen><para>All in all, our structure and data parts for the nuke_users table will look like the following:</para><screen><![CDATA[#
]]><![CDATA[# Table structure for table `nuke_users`
]]><![CDATA[#
]]><![CDATA[CREATE TABLE nuke_users (
]]><![CDATA[user_id int(11) NOT NULL auto_increment,
]]><![CDATA[name varchar(60) NOT NULL default ",
]]><![CDATA[username varchar(25) NOT NULL default ",
]]><![CDATA[user_email varchar(255) NOT NULL default ",
]]><![CDATA[femail varchar(255) NOT NULL default ",
]]><![CDATA[
]]><![CDATA[...many other fields of nuke_users follow here
]]><![CDATA[
]]><![CDATA[
]]><![CDATA[#
]]><![CDATA[# Dumping data for table `nuke_users`
]]><![CDATA[#
]]><![CDATA[INSERT INTO nuke_users VALUES (1, ", 'Anonymous', ", ", ",
]]><![CDATA['blank.gif', 'Nov 10, 2000', ",", ", ", ", 0, 0, ", ", ",
]]><![CDATA[", 10, ", 0, 0, 0, ", 0, ", ", 4096, 0, 0, 0, 0, 0, 1, 0,
]]><![CDATA[0, 1, 0, 0, 0, 10,NULL, 'english', 'D M d, Y g:i a', 0, 0, 0, NULL,
]]><![CDATA[1, 1, 1, 1, 1, 1, 1, 1, 0, 3, NULL, NULL, NULL);
]]><![CDATA[
]]><![CDATA[...many other user data follow here
]]><![CDATA[
]]></screen><para>In the above example, only a small part of the structure of the nuke_users<indexterm><primary>nuke_users</primary></indexterm> table is shown for brevity. You will also most probably have more than one user, so that the data part will also be much bigger (we only show the user data for user &ldquo;Anonymous<indexterm><primary>Anonymous</primary></indexterm>&rdquo;).</para><para>We can get a partial restore of the single nuke_users table in three ways:</para><orderedlist><listitem><para>We copy and paste the relevant structure and data parts from our backup<indexterm><primary>backup</primary></indexterm> file into a separate file that we will call partial_backup.<indexterm><primary>backup</primary></indexterm>sql. Then we use phpMyAdmin's &ldquo;SQL query<indexterm><primary>query</primary></indexterm>&rdquo; function (see <xref linkend="phpMyAdmin-navigation-bar-SQL">) to import the partial_backup.<indexterm><primary>backup</primary></indexterm>sql file, just as we do with any other file containing SQL queries.<indexterm><primary>queries</primary></indexterm> We enter the full path to partial_backup.<indexterm><primary>backup</primary></indexterm>sql in the &ldquo;textfile&rdquo; field of <xref linkend="fig-phpmyadmin-sql-query-2"> and click on &ldquo;Go&rdquo;.</para></listitem><listitem><para>We copy and paste the relevant structure and data parts from our backup<indexterm><primary>backup</primary></indexterm> file into the text area field above the &ldquo;Browse<indexterm><primary>Browse</primary></indexterm>&rdquo; button, then click on &ldquo;Go&rdquo;.</para></listitem><listitem><para>We don't use phpMyAdmin but use the shell command line instead. From the shell promt, we type:</para><screen><![CDATA[mysql -h dbhost -u dbuname -p dbname < partial_backup.sql
]]></screen><para>where dbhost,<indexterm><primary>dbhost</primary></indexterm> dbuname and dbname are exactly the same as in your config.php file(<xref linkend="config-php-file">).</para></listitem></orderedlist></sect2>
<sect2 id="restore-large-backup"><title>How to restore a large backup</title><para>If your backup file is really large (a few megabytes are enough), <acronym>PHP</acronym> will not be able to import it in the usual <acronym>CPU</acronym> time limit of 30 sec. that is set by most ISPs.<indexterm><primary>ISPs</primary></indexterm> The result will be an error and a corrupted or incomplete table. In this case you can proceed as follows:</para><itemizedlist><listitem><para>If you have access to the shell promt, login to your server with SSH and type the following on the shell prompt:</para><screen><![CDATA[mysql -h dbhost -u dbuname -p dbname < partial_backup.sql
]]></screen><para>where dbhost,<indexterm><primary>dbhost</primary></indexterm> dbuname and dbname are exactly the same as in your config.php file(<xref linkend="config-php-file">).</para></listitem><listitem><para>If you don't have shell access,<indexterm><primary>access</primary></indexterm> you can use an interface like MysqlFront (see <xref linkend="mysql-frontend">):</para></listitem></itemizedlist><warning>
<title>
The <acronym>PHP</acronym> <acronym>CPU</acronym> time limit may hit you in backups too!
</title>
<para>
Just as <acronym>PHP</acronym> may time out on a restore, it may timeout on a backup as well!. You are then left with the command line option , or some script solution along the lines of <xref linkend="backup-mysql-using-browser">, modified so that it only makes a backup of a piece of your data each time.
</para>
</warning>
</sect2>
</sect1>
<sect1 id="install-new-modules"><title>How to install new modules</title><para>
<figure id="fig-modules-3">
<title>
Administration panel: Modules.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1189;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1189;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1189;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1189;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Modules.</phrase>
</textobject>
<caption>
<para>Administration panel: Modules.</para>
</caption>
</mediaobject>
</figure>
</para><important>
<title>
Check versions!
</title>
<para>
Before we start, check that the version of the module you are about to install is compatible with the <application>PHP-Nuke</application> version of your installation!
</para>
</important>
<para>The add-on modules of <application>PHP-Nuke</application> are of various types (see <xref linkend="PHP-Nuke-add-on-modules"> for some examples), but can be grouped together in 3 different categories:</para><orderedlist><listitem><para>Modules that do not change the database structure (see <xref linkend="install-modules-with-no-database-change">).</para></listitem><listitem><para>Modules that change the database structure (see <xref linkend="install-modules-with-database-change">).</para></listitem><listitem><para>Modules that change both the database structure and the orininal <application>PHP-Nuke</application> files (see <xref linkend="install-modules-with-database-files-change">).</para></listitem></orderedlist><sect2 id="install-modules-with-no-database-change"><title>How to install modules that do not change the database structure</title><para>These are the simplest modules to install. Their installation consists only of copying the module's files in the aproppriate folders in <application>PHP-Nuke</application>. There are no changes to the original tables and no new tables involved.</para><para>These modules may consist of only a public part, only an administration<indexterm><primary>administration</primary></indexterm> part , or both. But how tell if a certain module requires a database modification or not? Generally, a module package comes with the following folders:</para><screen>
html <co id="modules-html">
html/modules <co id="modules-html-modules">
html/admin <co id="modules-html-admin">
html/images <co id="modules-html-images">
html/sql <co id="modules-html-sql">
</screen>
<calloutlist>
<callout arearefs="modules-html">
<para>
This is a container folder that is not involved in the installation.
</para>
</callout>
<callout arearefs="modules-html-modules">
<para>
The subfolders of this folder constitute the public part of the module and should be copied under a directory with the module's name in the <application>PHP-Nuke</application> modules folder.
</para>
</callout>
<callout arearefs="modules-html-admin">
<para>
The subfolders of this folder constitute the administration part of the module and should be copied under PHP-Nuke's admin folder.
</para>
</callout>
<callout arearefs="modules-html-images">
<para>
Contains any images used by the module. Its contents should be copied in the <application>PHP-Nuke</application> images folder.
</para>
</callout>
<callout arearefs="modules-html-sql">
<para>
Contains the file with all the necessary modification commands for the database, if any. It is the existence of such a file (sometimes not with the .sql ending) that suggests that the module in question requires changes in the database. However, its absence is not a sure sign that such a change is not needed at all: some modules will make their changes to the database on-the-fly, e.g. through some install.php <acronym>PHP</acronym> script that we will have to open with our browser during installation.
</para>
</callout>
</calloutlist>
</sect2>
<sect2 id="install-modules-with-database-change"><title>How to install modules that change the database structure</title><para>These modules,<indexterm><primary>modules</primary></indexterm> although they will not change any original <application>PHP-Nuke</application> files, they will require a change in the <application>PHP-Nuke</application> database.<indexterm><primary>base</primary></indexterm> The required change in the database may be of two types:</para><orderedlist><listitem><para>Some tables are appended to the database,<indexterm><primary>base</primary></indexterm> but without changing any of the existing ones.</para></listitem><listitem><para>The original <application>PHP-Nuke</application> tables must be changed.</para></listitem></orderedlist><para>The installation of these modules consists in the copying of their files into the appropriate folders (see <xref linkend="install-modules-with-no-database-change"> for the details, remember that they don't overwrite or change any original <application>PHP-Nuke</application> file) and the import of a .sql file (using phpMyAdmin,<indexterm><primary>Admin</primary></indexterm> as shown in <xref linkend="phpMyAdmin-navigation-bar-SQL">, or the command line as in <xref linkend="database-creation">), or the opening of some install.php file through the browser that will make the database changes automatically.</para></sect2>
<sect2 id="install-modules-with-database-files-change"><title>How to install modules that change the database structure and the files</title><para>There are module that, in order to function properly, require the addition of functions in the original files of <application>PHP-Nuke</application>. These modules will overwrite mainfile.php, modules.<indexterm><primary>modules</primary></indexterm>php, or some other file. </para><caution>
<title>
Beware of subsequent installations!
</title>
<para>
If you install a module that changes PHP-Nuke's original files, you may not be able to conduct the installation of another one that requires changes in those files too! The new module's installation script may not find the expected code to modify, since it will have been changed by the previous one.
</para>
<para>
For example, in <application>PHP-Nuke</application> 6.0 there were two interesting add-on modules, Indy News and Groups, that both required changes to be made in mainfile.php. In order to get them both to work, we had to do the changes in mainfile.php by hand, resulting in a file that contained a mix of modifications by both modules.
</para>
</caution>
<warning>
<title>
Automatic upgrades may not work any more!
</title>
<para>
In case you had to change the original tables of <application>PHP-Nuke</application> (i.e. you had not just to append some new tables to the database, but to change existing ones), then you may find out the next time you want to upgrade, the automatic upgrade scripts that come with each new <application>PHP-Nuke</application> version (see <xref linkend="upgrade-php-nuke">) do not work any more!
</para>
<para>
This is because the scripts will search for the original table structure to upgrade, but will find some new one instead. In this case it is recommended to have a look at the upgrade scripts and do the changes manually, using either a graphical frontend, like phpMyAdmin (<xref linkend="phpmyadmin">) or the MySQL command line (<xref linkend="database-creation">).
</para>
</warning>
<para>The same warning applies to file changes during upgrades:<indexterm><primary>upgrades</primary></indexterm> it is best to make the changes in the files by hand, also for those files of the new modules.<indexterm><primary>modules</primary></indexterm> Such a procedure can be very painful and time-consuming. It is recommended that you use a local test server for all these changes and that you do not upload the modified files, until you have tested them thoroughly and made all backups of the production system.<indexterm><primary>system</primary></indexterm> (See <xref linkend="fig-backup-db"> and <xref linkend="administration-functions">, for PHP-Nuke's own backup function,<indexterm><primary>function</primary></indexterm> <xref linkend="phpmyadmin"> for phpMyAdmin's functionality, which also includes a very good web interface<indexterm><primary>interface</primary></indexterm> to database backups and <xref linkend="backup-mysql-using-browser">, for home-made scripts that automate the backup work for you).</para></sect2>
</sect1>
<sect1 id="install-patches-correct-errors"><title>How to install patches and correct errors</title><para>From time to time it occurs that some functions of a certain <application>PHP-Nuke</application> version contain bugs, or that some others are in need of an update.<indexterm><primary>date</primary></indexterm> Here we will briefly discuss the most common problems that arise in such situations.<indexterm><primary>ations</primary></indexterm></para><tip>
<title>
Use the Forums!
</title>
<para>
If you are in search of a solution to a common problem, your first move should be to consult a Forum, like those of the authors: <ulink url="http://www.spaghettilearning.com/modules.php?name=Forums&amp;file=index&amp;c=1">PHP-Nuke Forum of spaghettibrain</ulink> (Claudio), or <ulink url="http://www.karakas-online.de/forum/phpnuke.html">PHP-Nuke Forum of karakas-online</ulink> (Chris). Of course, you should always use the search function of the Forums first, before asking a question that has been possibly asked (and answered) many times already.
</para>
</tip>
<para>Here is an example of the installation of a patch:<indexterm><primary>patch</primary></indexterm></para><para>Generally a patch consists of one or more files that will overwrite the buggy existing ones. The &ldquo;installation<indexterm><primary>installation</primary></indexterm>&rdquo; of the patch is thus nothing more than the simple overwriting of those files: foobar.<indexterm><primary>foobar</primary></indexterm>php (12Kb) will overwrite the existing file foobar.<indexterm><primary>foobar</primary></indexterm>php (13Kb) (notice that the name is the same, but the size differs). It is a good practice not to overwrite the old file, thus deleting it completely, but to move it to something like foobar.old or foobar.orig,<indexterm><primary>foobar.orig</primary></indexterm> so that you can easily restore it, should the new version present unexpected problems.</para><para>Example of a manual correction in the code:</para><para>Suppose our file consists of a number of lines:</para><screen><![CDATA[$qdb = "WHERE topic='$new_topic'";
]]><![CDATA[$sql_a = "SELECT topictext FROM ".$prefix."_topics WHERE topicid='$new_topic'";
]]><![CDATA[$result_a = $db->sql_query($sql_a)
]]><![CDATA[$row_a = $db->sql_fetchrow($result_a);
]]><![CDATA[$numrows_a = $db->sql_numrows($result_a);
]]><![CDATA[$topic_title = $row_a[topictext];
]]></screen><para>and we are told that we must replace the fourth one with </para><screen><![CDATA[$result_a = $db->sql_query($sql_a);
]]></screen><para>then, after we do this and save the file, our new file will look like:</para><screen><![CDATA[$qdb = "WHERE topic='$new_topic'";
]]><![CDATA[$sql_a = "SELECT topictext FROM ".$prefix."_topics WHERE topicid='$new_topic'";
]]><![CDATA[$result_a = $db->sql_query($sql_a);
]]><![CDATA[$row_a = $db->sql_fetchrow($result_a);
]]><![CDATA[$numrows_a = $db->sql_numrows($result_a);
]]><![CDATA[$topic_title = $row_a[topictext];
]]></screen><para>(Can you see the difference? <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject>)</para>
<para>Most decent text editors (see <xref linkend="editing-PHP-Nuke-files">) will display the line number for your orientation during such operations.<indexterm><primary>ations</primary></indexterm></para></sect1>
<sect1 id="find-all-registration-links"><title>How to find all registration links</title><para>Links pointing to the registration page </para><screen><![CDATA[modules.php?name=Your_Account&op=new_user
]]></screen><para>exist at various places in <application>PHP-Nuke</application> - and with various texts. To disable registration,<indexterm><primary>registration</primary></indexterm> it will not suffice to find them all and delete them from the code. This will not prevent a user from entering the above URL directly by hand in the address field of his browser. You will have to apply a solution like the one of <xref linkend="disable-registration">. Nevertheless, you may still wish to find and delete all links to the registration page <emphasis>after</emphasis> you have applied the solution of <xref linkend="disable-registration">. How do you proceed?</para><para>Place your mouse on a registration link and take note of the URL show in the status bar of your browser. Try to find some special string in it. The URL parameters are well suited for this. In the above registration URL,<indexterm><primary>URL</primary></indexterm> there are two of them, name (with value &ldquo;Your_Account<indexterm><primary>Your_Account</primary></indexterm>&rdquo;) and op (with value &ldquo;new_user<indexterm><primary>new_user</primary></indexterm>&rdquo;). The value of name is certainly not a uniquely identifying feature of the URL (you will encounter &ldquo;name=Your_Account<indexterm><primary>Your_Account</primary></indexterm>&rdquo; in many URLs, not only those for registration) , but the value of op certainly is. </para><para>Thus, you only have to search for &ldquo;new_user<indexterm><primary>new_user</primary></indexterm>&rdquo; . But not in the whole code. Since link texts have to be different for different languages, you can safely bet that the URLs you are looking for are going to contain text constants (see <xref linkend="General-PHP-Nuke-texts">). Your first attempt should thus concentrate in the language files:</para><screen><![CDATA[grep new_user language/*
]]><![CDATA[...
]]><![CDATA[language/lang-english.php:define("_ASREGISTERED",
]]><![CDATA["Don't have an account yet? You can
]]><![CDATA[<a href=\"modules.php?name=Your_Account&amp;op=new_user\">create one</a>.
]]><![CDATA[As a registered user you have some advantages like theme manager,
]]><![CDATA[comments configuration and post comments with your name.");
]]><![CDATA[language/lang-english.php:define("_YOUAREANON",
]]><![CDATA["You are Anonymous user. You can register for free by clicking
]]><![CDATA[<a href=\"modules.php?name=Your_Account&amp;op=new_user\">here</a>");
]]><![CDATA[language/lang-english.php:define("_MODULEUSERS",
]]><![CDATA["We are Sorry, but this section of our site is for
]]><![CDATA[<i>Registered Users Only.</i><br><br>You can register for free by clicking
]]><![CDATA[<a href=\"modules.php?name=Your_Account&op=new_user\">here</a>,
]]><![CDATA[then you can<br>access this section without restrictions. Thanks.<br><br>");
]]><![CDATA[...
]]></screen><para>You now see that user registration links (from the Your Account module) come in three flavours, containing the text constants _ASREGISTERED, _YOUAREANO<indexterm><primary>_YOUAREANO</primary></indexterm>N and _MODULEUSERS respectively. Now, all you have to do to find the exact places of the links in the code, is to search the <acronym>PHP</acronym> files for those three constants.<indexterm><primary>constants</primary></indexterm> You can then delete or modify the links you find, according to the context<indexterm><primary>context</primary></indexterm> and your liking.</para><para>A similar &ldquo;bottom-up<indexterm><primary>bottom-up</primary></indexterm>&rdquo; approach can be used to find the reason for an error, such as <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=353">Sorry, such file doesn't exist...</ulink> for example, which is discussed in <xref linkend="sorry-such-file-doesnt-exist">.</para></sect1>
<sect1 id="allow-anonymous-web-link-submissions"><title>How to allow anonymous web link submissions</title><para>
<figure id="fig-weblinks-5">
<title>
Administration panel: Web Links.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1190;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1190;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1190;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1190;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Web Links.</phrase>
</textobject>
<caption>
<para>Administration panel: Web Links.</para>
</caption>
</mediaobject>
</figure>
</para><para>Suppose you need to allow anonymous users to submit web links that then must be approved by an Administrator.<indexterm><primary>Administrator</primary></indexterm> Is this possible with the vanilla install of PHP-Nule?</para><para>It turns out that yes, it is - very easily indeed! But instead of just presenting you the solution, we will also describe how we arrived at it (see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=18795">Anonymous Web Link Submissions</ulink>):</para><para>We first thought that if the Web Links module was visible by all visitors, it would also allow them to suggest a link. We tried it, but we got the error:</para><blockquote><para>You are not a registered user or you have not logged in.</para><para>If you were registered you could add links on this website.<indexterm><primary>website</primary></indexterm></para><para>Becoming a registered user is a quick and easy process.</para><para>Why do we require registration for access to certain features?<indexterm><primary>features</primary></indexterm></para><para>So we can offer you only the highest quality content,</para><para>each item is individually reviewed and approved by our staff.</para><para>We hope to offer you only valuable information.<indexterm><primary>information</primary></indexterm></para></blockquote><para>Obviously, <application>PHP-Nuke</application> made a check if this was a registered user - and issued that statement. But where was this check located in the code?</para><para>To find it, we used the same bottom-up approach of <xref linkend="sorry-such-file-doesnt-exist"> and <xref linkend="find-all-registration-links">: </para><para>We first had to find the place where the above error was echoed. We thus searched the whole code tree for all occurences of a word that most probably would appear only in the error above - we chose the word &quot;valuable&quot;. It turned out that the word &quot;valuable&quot; was in some unrelated text consntants<indexterm><primary>consntants</primary></indexterm> - but it was also in the _LINKSNOTUSER7 text constant that was translated in all modules/Web_Links/language/lang-XXXX.php files!</para><para>Armed with this information,<indexterm><primary>information</primary></indexterm> we only had to do a second search, this time for all occurences of the string &quot;_LINKSNOTUSER&quot; in the whole code tree of <application>PHP-Nuke</application>. We got again dozens of language files in the output, but we also got the modules/Web_Links/index.<indexterm><primary>index</primary></indexterm>php file. Indeed, if at all, it must be this file where the check is made! </para><para>We thus checked the relevant lines of modules/Web_Links/index.<indexterm><primary>index</primary></indexterm>php and the code went like this:</para><screen><![CDATA[if (is_user($user) || $links_anonaddlinklock == 1) {
]]><![CDATA[
]]><![CDATA[--> do the work here <--
]]><![CDATA[
]]><![CDATA[}else {
]]><![CDATA[ echo "<center>"._LINKSNOTUSER1."<br>"
]]><![CDATA[ .""._LINKSNOTUSER2."<br><br>"
]]><![CDATA[ .""._LINKSNOTUSER3."<br>"
]]><![CDATA[ .""._LINKSNOTUSER4."<br>"
]]><![CDATA[ .""._LINKSNOTUSER5."<br>"
]]><![CDATA[ .""._LINKSNOTUSER6."<br>"
]]><![CDATA[ .""._LINKSNOTUSER7."<br><br>"
]]><![CDATA[ .""._LINKSNOTUSER8."";
]]><![CDATA[}
]]></screen><para>So that's where the check is made! You can see it for yourself, because the code is almost speaking natural language:</para><blockquote><para>If is user or anon add link</para></blockquote><para>We first thought we had to remove the check &quot;if is user&quot;, but then we saw that &quot;or $links_anonaddlinklock == 1&quot; which made us suspicious. So there was some kind of configuration variable ( $links_anonaddlinklock) which can control the outcome of the test!</para><para>We know from experience that such variables are set in a separate <acronym>PHP</acronym> file, in the same folder of the module.<indexterm><primary>module</primary></indexterm> If you didn't have this experience, then you would just have to do a third search for all occurences of the string &quot;links_anonaddlinklock&quot; in the text of all files - there shouldn't be that many.</para><para>Indeed, $links_anonaddlinklock is set in modules/Web_Links/l_config.php:<indexterm><primary>l_config.php</primary></indexterm></para><screen><![CDATA[# $links_anonaddlinklock: Lock Unregistered users from Suggesting New Links?
]]><![CDATA[ (0=Yes 1=No)
]]><![CDATA[
]]><![CDATA[...many other comments
]]><![CDATA[
]]><![CDATA[######################################################################
]]><![CDATA[
]]><![CDATA[...many other variables
]]><![CDATA[
]]><![CDATA[$links_anonaddlinklock = 0;
]]></screen><para>So you just have to set</para><screen><![CDATA[$links_anonaddlinklock = 1;
]]></screen><para>in modules/Web_Links/l_config.<indexterm><primary>config</primary></indexterm>php and any user, also unregistered ones, will be able to suggest Web Links!</para><tip>
<title>
A general approach to problem solving
</title>
<para>
You can use this bottom-up approach to solve many similar problems of your daily work as an administrator of a <application>PHP-Nuke</application> system.
</para>
</tip>
</sect1>
<sect1 id="disable-DEBUG-mode"><title>How to disable DEBUG mode</title><para>You may have already come across those errors that enter automatically a DEBUG mode and output a more descriptive message of what happened (we saw how to do this ourselves in <xref linkend="descriptive-error-message">):</para><screen><![CDATA[General Error
]]><![CDATA[Couldn't update private forum permissions
]]><![CDATA[DEBUG MODE
]]><![CDATA[SQL Error : 1064 You have an error in your SQL syntax near ' 1)' at line 2
]]><![CDATA[INSERT INTO nuke_bbauth_access (forum_id, group_id, auth_mod) VALUES (1, , 1)
]]><![CDATA[Line : 425
]]><![CDATA[File : /web/htdocs/www.yoursite.net/home/html69/modules/Forums/admin/admin_ug_auth.php
]]></screen><para>By the way, this is the error discussed in <xref linkend="error-update-private-forum-permissions">. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject>You may not want to show so many details to your users and wish you could disable the DEBUG mode. But to disable the DEBUG mode, you have first to find where to do it:</para>
<para>In cases like this, search is your friend (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=307">Can I disable the DEBUG mode</ulink>): search for DEBUG in all texts of all files in all subdirectories of a <application>PHP-Nuke</application> installation.<indexterm><primary>installation</primary></indexterm> You will get a handful of lines:</para><screen><![CDATA[/usr/bin/find ./ -type f -print0 | /usr/bin/xargs -0 /usr/bin/grep DEBUG
]]><![CDATA[./includes/constants.php://define('DEBUG', 1); // Debugging on
]]><![CDATA[./includes/constants.php:define('DEBUG', 1); // Debugging off
]]><![CDATA[./includes/functions.php: if ( DEBUG && ( $msg_code == GENERAL_ERROR ||
]]><![CDATA[$msg_code == CRITICAL_ERROR ) )
]]><![CDATA[./includes/functions.php: // Add on DEBUG info if we've enabled debug mode
]]><![CDATA[and this is an error. This
]]><![CDATA[./includes/functions.php: // prevents debug info being output for general
]]><![CDATA[messages should DEBUG be
]]><![CDATA[./includes/functions.php: if ( DEBUG && ( $msg_code == GENERAL_ERROR ||
]]><![CDATA[$msg_code == CRITICAL_ERROR ) )
]]><![CDATA[./includes/functions.php: $msg_text = $msg_text . '<br />
]]><![CDATA[<br /><b><u>DEBUG MODE</u></b>' . $debug_text;
]]><![CDATA[./modules/WebMail/pop3.php: var $DEBUG=0;
]]><![CDATA[./modules/WebMail/pop3.php: if ($this->DEBUG) echo "<b>Sending
]]><![CDATA[Command: </b>".$command."<br>";flush();
]]><![CDATA[./modules/WebMail/pop3.php: if ($this->DEBUG) echo "<b>
]]><![CDATA[Result OK: </b><br>";flush();
]]><![CDATA[./modules/WebMail/pop3.php: if ($this->DEBUG) echo "<b>
]]><![CDATA[Openning Connection to: </b>".$this->hostname."<br>";flush();
]]><![CDATA[./modules/WebMail/pop3.php: if ($this->DEBUG) echo "<b>
]]><![CDATA[Connection opened </b><br>";flush();
]]></screen><para>It is clear that the DEBUG constant is set in includes/constants.<indexterm><primary>constants</primary></indexterm>php (see the first two lines of the above results) and is used in the rest of the files.</para><para>Thus, to disable DEBUG mode, you only need to edit includes/constants.<indexterm><primary>constants</primary></indexterm>php and change</para><screen><![CDATA[// Debug Level
]]><![CDATA[define('DEBUG', 1); // Debugging on
]]><![CDATA[//define('DEBUG', 1); // Debugging off
]]></screen><para>to</para><screen><![CDATA[// Debug Level
]]><![CDATA[//define('DEBUG', 1); // Debugging on
]]><![CDATA[define('DEBUG', 1); // Debugging off
]]><![CDATA[
]]></screen></sect1>
</chapter>
<chapter id="miscellaneous"><title>Miscellaneous</title><para>This chapter contains material that did not fit anywhere else, because the content was too specific, too advanced, or even too eccentric to be presented elsewhere. This does not mean that you should skip it, however. You will find some tips and tricks that may save the day - and you will learn some techniques applicable not only to PHP-Nuke, but to other areas as well, such as <acronym>PHP</acronym> programming or website management - so please read on!<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_smile.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_smile.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_smile.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_smile.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject></para>
<para>The topics we cover are:</para><itemizedlist><listitem><para>How to change the Home module (<xref linkend="change-Home-module">),</para></listitem><listitem><para>How to use <application>PHP-Nuke</application> under SSL (<xref linkend="PHP-Nuke-under-SSL">),</para></listitem><listitem><para>How to change <acronym>PHP</acronym> parameters when you don't have access to php.ini (<xref linkend="change-PHP-parameters">),</para></listitem><listitem><para>How to display HTML code in a FAQ (<xref linkend="display-html-code-in-faq"> ),</para></listitem><listitem><para>How to enter thousands of web links (<xref linkend="enter-thousands-of-web-links">),</para></listitem><listitem><para>How to enter thousands of download links (<xref linkend="enter-thousands-of-download-links">),</para></listitem><listitem><para>How to check the validity of thousands of web links (<xref linkend="check-validity-of-web-links">),</para></listitem><listitem><para>How to enter thousands of ephemerids (<xref linkend="enter-thousands-of-ephemerids">),</para></listitem><listitem><para>How to make the Encyclopedia international (<xref linkend="make-encyclopedia-international">),</para></listitem><listitem><para>How to find the user name in a module (<xref linkend="find-user-name">), </para></listitem><listitem><para>How to correct thousands of users fields (<xref linkend="correct-thousands-of-users-fields">),</para></listitem><listitem><para>How to size the select boxes in a module (<xref linkend="size-select-boxes">),</para></listitem><listitem><para>How to deal with date and time (<xref linkend="date-time">),</para></listitem><listitem><para>How to deal with quotes in the site's name (<xref linkend="deal-with-quotes-in-sitename">),</para></listitem><listitem><para>How to embed a Flash object in <application>PHP-Nuke</application> News (<xref linkend="flash-php-nuke-news">),</para></listitem><listitem><para>How to backup your MySQL database using only the browser (<xref linkend="backup-mysql-using-browser">).</para></listitem></itemizedlist><sect1 id="change-Home-module"><title>How to change the Home module</title><para>
<figure id="fig-modules-2">
<title>
Administration panel: Modules.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1191;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1191;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1191;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1191;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Modules.</phrase>
</textobject>
<caption>
<para>Administration panel: Modules.</para>
</caption>
</mediaobject>
</figure>
</para><para>In PHP-Nuke, the &ldquo;Home&rdquo; module is the module that is displayed in the central column of the index.php<indexterm><primary>index.php</primary></indexterm> page. The default Home module is the News module, i.e., upon opening the index.php<indexterm><primary>index.php</primary></indexterm> page, we get the usual news summary of the News module in the central column. However, you may want to change this behaviour and display, say, the Downloads<indexterm><primary>ads</primary></indexterm> module in the Home instead. You could of course use some kind of redirection (see <xref linkend="redirect-users-to-homepage"> and <xref linkend="redirect-users-to-login-and-back"> for ideas) to redirect your visitors to the Downloads module,<indexterm><primary>module</primary></indexterm> however this is not necessary: <application>PHP-Nuke</application> allows you to change the module that will be &ldquo;put in Home&rdquo; from the modules administration panel (<xref linkend="administration-functions">).</para><para>Normally, to change the Home module,<indexterm><primary>module</primary></indexterm> you proceed as follows: go to the administration panel, click on &quot;Modules&quot;<indexterm><primary>Modules</primary></indexterm>. You get a table of modules (<xref linkend="fig-modules-admin-3">). </para><para>
<figure id="fig-modules-admin-3">
<title>
Modules administration panel.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1192;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1192;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1192;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1192;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Modules administration panel.</phrase>
</textobject>
<caption>
<para>Modules administration panel.</para>
</caption>
</mediaobject>
</figure>
</para><para>Find the line that contains the information on the &quot;Downloads&quot;<indexterm><primary>Downloads</primary></indexterm> module. There, there is a link &quot;Put in Home&quot;, besides the &quot;Edit&quot;<indexterm><primary>Edit</primary></indexterm> and &quot;Delete&quot; links. Click on &quot;Put in Home&quot; and answer with &quot;Yes&quot; the question that follows (you may have to scroll to see it):</para><screen><![CDATA[Default Homepage Module
]]><![CDATA[Are you sure you want to change your Homepage from Web_Links To Downloads?
]]><![CDATA[[ No | Yes ]
]]></screen><para>Then the Downloads module will be your &quot;Home&quot;. </para><para>However, this may not work with some themes like Sand_Journey (which is one of the standard ones). <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_frown.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_frown.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_frown.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_frown.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject></para>
<para>The reason is the following code in index.<indexterm><primary>index</primary></indexterm>php (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=331">Setting a module to be shown on Home page</ulink>):</para><screen><![CDATA[if (file_exists("themes/$ThemeSel/module.php")) {
]]><![CDATA[include("themes/$ThemeSel/module.php");
]]></screen><para>For the Sand_Journey theme (i.e. when $ThemeSel is &quot;Sand_Journey&quot;<indexterm><primary>Sand_Journey</primary></indexterm>), this means that themes/Sand_Journey/module.php file is included in index.php,<indexterm><primary>index.php</primary></indexterm> if it exists. But if it is included, it changes the default module, because the module.php<indexterm><primary>module.php</primary></indexterm> file for the Sand_Journey theme contains:</para><screen><![CDATA[<?php
]]><![CDATA[$default_module = "News";
]]><![CDATA[?>
]]></screen><para>overriding any other settings. Thus, to be able to change the Home module with such a theme, you have to rename, delete, or remove the module.php file from the theme folder. No file, no cry. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_cool.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_cool.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_cool.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_cool.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject></para>
</sect1>
<sect1 id="PHP-Nuke-under-SSL"><title>How to use <application>PHP-Nuke</application> under SSL</title><para>SSL encrypts data at layer 6 of the <ulink url="http://en2.wikipedia.org/wiki/OSI_model">OSI model</ulink> (FIXME:<indexterm><primary>FIXME</primary></indexterm> image!). SSL doesn't necessarily keep hackers out, but rather encrypts the data<indexterm><primary>data</primary></indexterm> so that IF a hacker is listening, it renders the data useless to the hacker.<indexterm><primary>hacker</primary></indexterm> SSL is mainly used for e-commerce but is not limited to it, so you can certainly use it with <application>PHP-Nuke</application>.</para><para>To install SSL on your system,<indexterm><primary>system</primary></indexterm> you need the <ulink url="http://www.openssl.org">openSSL</ulink> package and the <ulink url="http://www.modssl.org">Apache modSSL module</ulink>. </para><para>SSL will, by default, slow a site down. However not considerably, it does slow a site down due to encryption algorythms (don't worry, it's not a slowdown analogous to broadband vs. dialup).</para><para>SSL will NOT protect you from a user that knows the <application>PHP-Nuke</application> password of a user or is determined to apply the latest exploit to your site. It will only protect the traffic from eavesdroppers on the line. Nothing can totally protect you from this kind of attack - unless you probably sit the whole day in front of your computer, reading security advisories<indexterm><primary>advisories</primary></indexterm> and taking action the very minute you read something about a new <application>PHP-Nuke</application> vulnerability.<indexterm><primary>vulnerability</primary></indexterm> Of course you can take security measures for your site (and you should take them, see <xref linkend="security-measures">), but you should not conclude that your site is now secure just because you are using SSL!</para><para>After installing Apache with openSSL and modSSL to make your site more secure, you will be connecting to it with the HTTPS protocol and, accordingly, your site will be accessible as https://www.yoursite.com (notice the extra &ldquo;s&rdquo; after &ldquo;http&rdquo;). But now every page of your site popps up with a Seuciryt Information Alert<indexterm><primary>Alert</primary></indexterm> like this:</para><screen><![CDATA[This Page contains both secure and nonsecure items.
]]><![CDATA[Do you want to display the nonsecure items?
]]><![CDATA[Yes - No - More Info
]]></screen><para>Of course, this is normal after installation of SSL.<indexterm><primary>SSL</primary></indexterm> The reason is that many <application>PHP-Nuke</application> blocks get their images from other sites (e.g. weather blocks (<xref linkend="PHP-Nuke-Meteosat-block">), comics blocks (<xref linkend="PHP-Nuke-comic-block">, <xref linkend="PHP-Nuke-Daily-Comic-module">), <ulink url="http://www.humpa.com/phpnuke/modules.php?name=Downloads&amp;d_op=viewdownload&amp;cid=2">daily babe blocks</ulink> ...). You will find out that the browser will nerve you with questions like the above and will NOT display images,<indexterm><primary>images</primary></indexterm> showing rather a broken key in their place, if the images come from outside the SSL domain.<indexterm><primary>domain</primary></indexterm></para><para>The only solution to this annoyance is to write &quot;SSL versions&quot; of the relevant blocks that will store the image in a local directory and then display the image from that directory, instead from the remote one.</para><para>To save the image locally, you can use for example:</para><screen><![CDATA[ require_once "includes/SSL.php";
]]><![CDATA[ $myurl = "http://www.someremotesite.com/somedir/someimage.jpg";
]]><![CDATA[ $myfile = "localtmpdir/mylocalimage.jpg";
]]><![CDATA[ $content = "";
]]><![CDATA[ saveimage($myurl, $myfile, $content);
]]></screen><para>in the block code, where includes/SSL.<indexterm><primary>SSL</primary></indexterm>php is</para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[function saveimage($imagefileurl, $tempfile, &$content) {
]]><![CDATA[
]]><![CDATA[if (time() - filemtime($tempfile) > 3600); {
]]><![CDATA[ if (!($imagefile = fopen( "$imagefileurl", "rb"))) {
]]><![CDATA[ $content .= "$imagefileurl<br> could not be opened<br>";
]]><![CDATA[ die();
]]><![CDATA[ }
]]><![CDATA[
]]><![CDATA[ $imagecontent .= fread($imagefile, 300000);
]]><![CDATA[ fclose($imagefile);
]]><![CDATA[
]]><![CDATA[ if (!($localimagefile = fopen($tempfile , "wb"))) {
]]><![CDATA[ $content .= "$tempfile<br> could not be opened<br>";
]]><![CDATA[ die();
]]><![CDATA[ }
]]><![CDATA[
]]><![CDATA[ fwrite($localimagefile, $imagecontent);
]]><![CDATA[ fclose($localimagefile);
]]><![CDATA[
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[return 1;
]]><![CDATA[
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[?>
]]></screen><para>the idea being that we only download the remote file to the local one if the remote file's modification time is older that one hour (3600 sec.).</para><para>There are probably better ways to do this - you could for example use Cache-Lite<indexterm><primary>Cache-Lite</primary></indexterm> (<xref linkend="cache-lite">) to cache the image file in a local cache directory, see <xref linkend="caching-php-nuke"> and <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=130">How to accelerate PHP-Nuke</ulink>. A discussion thread is in <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=18047">SSL on a phpnuke site</ulink>.</para><para>If you want to restrict SSL only on certain directories for the above reasons, you wil have to find a way to enforce the HTTPS protocol in some directories and enforce HTTP on others. Note that will have to enforce HTTP on the directories that don's need encryption,<indexterm><primary>encryption</primary></indexterm> otherwise a secure (and slow) connection will still be possible and your users might not notice that they are still using encryption in pages that don't matter (if they come to those pages from an encrypted<indexterm><primary>encrypted</primary></indexterm> page through a relative link, for example).</para><para>You can try mod_rewrite <xref linkend="mod-rewrite">) to force HTTPS on some URLs and force HTTP on others: using SERVER_PORT,<indexterm><primary>SERVER_PORT</primary></indexterm> you can check the current port is not 443 (the standard HTTPS port), and thus to force HTTPS when entering the /dir/ directory, use:</para><screen><![CDATA[# /dir/.htaccess
]]><![CDATA[RewriteEngine On
]]><![CDATA[RewriteCond %{SERVER_PORT}!443
]]><![CDATA[RewriteRule ^(.*)$ https://www.x.com/dir/$1 [R,L]
]]></screen><para>And because HTTPS is slower than HTTP,<indexterm><primary>HTTP</primary></indexterm> take the users out of HTTPS mode when they leave the /dir/ directory by:</para><screen><![CDATA[# /.htaccess
]]><![CDATA[RewriteEngine On
]]><![CDATA[RewriteCond %{SERVER_PORT} 443
]]><![CDATA[RewriteRule ^(.*)$ https://www.x.com/$1 [R,L]
]]></screen><para>The above code should be in a .htaccess file (<xref linkend="htaccess-file">) in the respective directory, but you can achieve the same result much faster if you have access to the web server configuration file and use the &lt;Directory&gt; directive, as described in <xref linkend="htaccess-file">. See also <ulink url="http://www.webmasterworld.com/forum13/3345.htm">Using mod_rewrite to force SSL</ulink> and <ulink url="http://www.webmasterworld.com/forum92/600.htm">More on rewrites</ulink>.</para><screen><![CDATA[
]]></screen></sect1>
<sect1 id="change-PHP-parameters"><title>How to change <acronym>PHP</acronym> parameters when you don't have access to php.ini</title><para>Unless you have your own &ldquo;root<indexterm><primary>root</primary></indexterm>&rdquo; server,<indexterm><primary>server</primary></indexterm> you are most probably sharing the same hardware with a few thousand other so-called &ldquo;virtual<indexterm><primary>virtual</primary></indexterm>&rdquo; domains.<indexterm><primary>domains</primary></indexterm> For this reason, it is all too natural that your ISP will deny you access<indexterm><primary>access</primary></indexterm> to the system-wide php.ini file (usually located under /etc). Whatever value you enter there, is going to affect all the virtual domains<indexterm><primary>domains</primary></indexterm> running on that machine!</para><para>But what to do if you find out that you must change a setting and you are told to change it in php.ini?<indexterm><primary>php.ini</primary></indexterm> Fortunately, there is an alternative way - and once again the .htaccess file (see <xref linkend="htaccess-file">) comes to your rescue:<indexterm><primary>rescue</primary></indexterm></para><para>To set register_globals to off (a good idea from a security point of view, see <xref linkend="security-measures">), for example, add </para><screen><![CDATA[php_flag register_globals off
]]></screen><para>to the .htaccess file in the <application>PHP-Nuke</application> root directory.</para><para>To set magic_quotes to off (a bad idea from a security point of view, see <xref linkend="security-measures">), you can add the following line to the .htaccess file in the <application>PHP-Nuke</application> root<indexterm><primary>root</primary></indexterm> directory:</para><screen><![CDATA[php_flag magic_quotes_gpc off
]]></screen><para>To set &quot;display_errors&quot;<indexterm><primary>display_errors</primary></indexterm> to off, add:</para><screen><![CDATA[php_flag display_errors off
]]></screen><para>while to set the include path (see <xref linkend="Include-path">), you can add</para><screen><![CDATA[php_value include_path ]]>&ldquo;<![CDATA[your/include/path/here]]>&rdquo;<![CDATA[
]]></screen><para>If you get a memory limit error like:</para><screen><![CDATA[Fatal error: Allowed memory size of 8388608 bytes exhausted
]]><![CDATA[(tried to allocate 67584 bytes) in xxx/xxxxxxx/xxxxx
]]></screen><para>then you can try to increase allocated memory with</para><screen><![CDATA[php_value memory_limit ]]>&ldquo;<![CDATA[16M]]>&rdquo;<![CDATA[
]]></screen><para>although you will probably not achieve the desired result, due to restrictions that your ISP has set in place.</para><para>To change the maximum execution time limit of your <acronym>PHP</acronym> scripts, add:</para><screen><![CDATA[php_value max_execution_time 60
]]></screen><para>This will set the time limit to 60 seconds.<indexterm><primary>seconds</primary></indexterm> But if you are not allowed to change php.ini,<indexterm><primary>php.ini</primary></indexterm> it is doudtful that you will be allowed to change the value of max_execution_time in a .htaccess file. If you <emphasis>can</emphasis> do it, however, then the .htaccess method gives you the flexibility to set different time limits in different directories - and thus different scripts that reside therein. See also <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=407">Page genration time too long</ulink>.</para><para>As you have guessed by now <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject>, the general syntax is:</para>
<screen><![CDATA[php_value PHP-variable value
]]></screen></sect1>
<sect1 id="display-html-code-in-faq"><title>How to display HTML code in a FAQ</title><para>
<figure id="fig-faq-2">
<title>
Administration panel: FAQ.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1193;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1193;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1193;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1193;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: FAQ.</phrase>
</textobject>
<caption>
<para>Administration panel: FAQ.</para>
</caption>
</mediaobject>
</figure>
</para><para>Using standard tools of a <productname>Linux</productname> system,<indexterm><primary>system</primary></indexterm> like <ulink url="http://www.gnu.org/software/sed/manual/sed.html">sed</ulink> and <ulink url="http://www.gnu.org/manual/gawk-3.0.3/gawk.html">awk</ulink>, you can automate code generation for some highly repetitive code fragments, like the one in the following example:</para><para>Suppose you want to display a table of smilies that are available on your system.<indexterm><primary>system</primary></indexterm> Each row should show the smiley and the code needed to insert it in an article.<indexterm><primary>article</primary></indexterm> The code that does the job is <ulink url="http://www.karakas-online.de/various/phpnuke-faq-code-1">phpnuke-faq-code-1</ulink>, for only one smiley, icon_smile.gif:</para><screen><![CDATA[<table width='100%' border='0' cellspacing='0' cellpadding='3'>
]]><![CDATA[<tr><td>
]]><![CDATA[<a> <img src="./modules/Forums/images/smiles/icon_smile.gif"> </a>
]]><![CDATA[</td><td><b>
]]><![CDATA[&a& &img src="./modules/Forums/images/smiles/icon_smile.gif"& &/a&
]]><![CDATA[</b></td></tr>
]]><![CDATA[</table>
]]></screen><para>To automate the code generation process for all the smilies you have, do:</para><screen><![CDATA[cd /usr/local/httpd/htdocs/nuke6/html
]]><![CDATA[ll modules/Forums/images/smiles/* | awk '{print $9}' > smilies
]]></screen><para>That is, you change to the html directory, list all smilies from the modules/Forums/images/smiles directory and let awk print the 9th field of each line - this is the file name of the smiley. The output is redirected to the smilies file, which will thus contain a list of all smiley filenames.</para><para>Create a <ulink url="http://www.karakas-online.de/various/phpnuke-faq-code-2">sed script that produces the HTML code for the smilies</ulink> and put it in a file named &ldquo;sedscr<indexterm><primary>sedscr</primary></indexterm>&rdquo; (for sed script):</para><screen><![CDATA[s/\(^.*$\)/<tr><td><a> <img src="\1"> <\/a>\
]]><![CDATA[<\/td><td><b>\
]]><![CDATA[\&a\& \&img src="\1"\& \&\/a\&\
]]><![CDATA[<\/b><\/td><\/tr>\
]]><![CDATA[/
]]></screen><para>and run sed on the previously created smilies file, using the above script as the &ldquo;sed script&rdquo;. For this, just run the <ulink url="http://www.karakas-online.de/various/runsed">runsed</ulink> script:</para><screen><![CDATA[runsed sedscr smilies
]]></screen><para>(runsed accepts two arguments: the sed script and the file to operate on). This produces the right code for our FAQ.<indexterm><primary>FAQ</primary></indexterm> You just have to add</para><screen><![CDATA[<table width='100%' border='0' cellspacing='0' cellpadding='3'>
]]><![CDATA[<tr><td>
]]></screen><para>at the beginning and</para><screen><![CDATA[</table>
]]></screen><para>at the end.</para></sect1>
<sect1 id="enter-thousands-of-web-links"><title>How to enter thousands of web links</title><para>
<figure id="fig-weblinks-2">
<title>
Administration panel: Web Links.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1194;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1194;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1194;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1194;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Web Links.</phrase>
</textobject>
<caption>
<para>Administration panel: Web Links.</para>
</caption>
</mediaobject>
</figure>
</para><para>You have gathered, or you have found , thousands of web links that you would like to enter in the <application>PHP-Nuke</application> Web Links module.<indexterm><primary>module</primary></indexterm> You don't want to do this manually. You can use <ulink url="http://www.gnu.org/software/sed/sed.html">sed</ulink> to produce the MySQL commands in a script file that you will then feed<indexterm><primary>feed</primary></indexterm> to MySQL,<indexterm><primary>MySQL</primary></indexterm> as described in <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=113">How to enter thousands of web links in PHP-Nuke</ulink>.</para><para>The first step is of course to find the page that contains all the links you need. This may be a HTML file, but it may also be a CVS file from an exported MS Access data - this doesn't matter, the procedure is the same: edit the source with sed to convert every line that has a link and a description to an SQL command that inserts the link and its description to the aproppriate table.</para><para>Example: Let's consider the page <ulink url="http://dmoz.org/Computers/Programming/Languages/PHP/Scripts/Content_Management/PHP-Nuke/">Content Management - PHP-Nuke</ulink> of the Open Directory (DMOZ) for a real world example. Save it as dmoz.html.<indexterm><primary>dmoz.html</primary></indexterm> To enter all the web links contained in dnoz.html into the WEB_Links module<indexterm><primary>module</primary></indexterm><footnote><para>If you are looking for a ready-made ODP module for PHP-Nuke, see <xref linkend="php-nuke-ODP-module">.</para></footnote>, we have to create the appropriate MySQL commands. To this end, save the following sed script under the name &quot;sedscr_downloads&quot;<indexterm><primary>sedscr_downloads</primary></indexterm>:</para><screen><![CDATA[s/<li><a href="\([^"]*\)">\(.*\)<\/a>\(.*\)$/INSERT INTO nuke_links_links
]]><![CDATA[( lid, cid, sid, title, url, description, date, name, email, hits, submitter, linkratingsummary, totalvotes, totalcomments )
]]><![CDATA[VALUES ( '0', '100', '0', '\2', '\1', '\3', '2003-06-23 06:05:45',
]]><![CDATA[", ", ", ", ", ", ");/p
]]></screen><para>This is a one-line sed command that creates the SQL INSERT query for every line of dmoz.html that contains a link. It takes the links's URL,<indexterm><primary>URL</primary></indexterm> title and description and stores them in sed's internal numbered fields 1, 2 and 3 respectively. It then uses the values of those fields [you can see them as escaped numbers \1, \2 and \3 in the VALUES part of the query) to fill the appropriate fields of the nuke_links_links table. You can download this sed script from <ulink url="http://www.karakas-online.de/various/sedscr_downloads">sedscr_downloads</ulink>. Adapt sedscr_downloads to your situation (e.g. change cid from 100 to the right category id, add values for name and email, change the date or the prefix of the links_links table). Then, run it as follows:</para><screen><![CDATA[sed -n -f sedscr_downloads dmoz.html > dmoz.sql
]]></screen><para>This will produce the file <ulink url="http://www.karakas-online.de/various/dmoz.sql">dmoz.sql</ulink>, containing lines like this one:</para><screen><![CDATA[INSERT INTO nuke_links_links( lid, cid, sid, title, url, description,
]]><![CDATA[date, name, email, hits, submitter, linkratingsummary, totalvotes,
]]><![CDATA[totalcomments ) VALUES ( '0', '100', '0', 'PHPNuke: Management and Programming',
]]><![CDATA['http://www.karakas-online.de/EN-Book/', ' - This tutorial describes the
]]><![CDATA[installation and structure of PHPNuke. It also delves into more advanced issues,
]]><![CDATA[like the programming of PHPNuke blocks and modules.', '2003-06-23 06:05:45',
]]><![CDATA[", ", ", ", ", ", ");
]]></screen><para>A line like the above will insert a Web Link in the module,<indexterm><primary>module</primary></indexterm> when ran from the MySQL command line. As you can see, <ulink url="http://www.karakas-online.de/various/dmoz.sql">dmoz.sql</ulink> contains the complete set of INSERT commands for all links contained in dmoz.html.<indexterm><primary>dmoz.html</primary></indexterm> To execute the commands from MySQL,<indexterm><primary>MySQL</primary></indexterm> type</para><screen><![CDATA[mysql < dmoz.sql
]]></screen><para>and all links will be inserted in the Web Links module.<indexterm><primary>module</primary></indexterm> </para><tip>
<title>
A big time saver!
</title>
<para>
If you have thousands (or even hundreds) of web links to enter, this method will save you days of typing! That's the power of sed!
</para>
</tip>
<para>Since I used <ulink url="http://www.dmoz.org">DMOZ</ulink> (or ODP,<indexterm><primary>ODP</primary></indexterm> Open Directory Project) as an example, let me add that there are a lot of scripts out there that can help you include the DMOZ data in your website.<indexterm><primary>website</primary></indexterm> An example is <ulink url="http://www.bie.no/products/phpodp/index.php">phpODP</ulink>. phpODP enables you to add the content of The Open Directory Project to your own website.<indexterm><primary>website</primary></indexterm> You can let your visitors browse the categories, or search the directory - 100% locally on your site. The content is updated in real-time - so when ODP updates,<indexterm><primary>dates</primary></indexterm> you update!</para><tip>
<title>
Search for ODP tools in ODP itself!
</title>
<para>
There is even an ODP category that is devoted to scripts and tools that can scrap ODP data for you: <ulink url="http://dmoz.org/Computers/Internet/Searching/Directories/Open_Directory_Project/Use_of_ODP_Data/Upload_Tools">Computers: Internet: Searching: Directories: Open Directory Project: Use of ODP Data: Upload Tools</ulink> . It includes links to more than 20 tools that can do this, so I think one of those should fit your purposes, if the method described here is not the right one for you. In any case, it is a source of a wealth of ideas that you can explore!
</para>
</tip>
</sect1>
<sect1 id="enter-thousands-of-download-links"><title>How to enter thousands of download links</title><para>
<figure id="fig-downloads-2">
<title>
Administration panel: Downloads.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1195;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1195;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1195;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1195;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Downloads.</phrase>
</textobject>
<caption>
<para>Administration panel: Downloads.</para>
</caption>
</mediaobject>
</figure>
</para><para>You have gathered, or you have found , thousands of download links that you would like to enter in the <application>PHP-Nuke</application> Downloads module.<indexterm><primary>module</primary></indexterm> You don't want to do this manually. You can use a <acronym>PHP</acronym> script to read the links and create the file with the SQL commands for you.</para><para>Put the following script (which you can download from <ulink url="http://www.humpa.com/news/downloadadd.txt">downloadadd.txt</ulink>) in the <application>PHP-Nuke</application> root directory (the directory where also the config.php<indexterm><primary>config.php</primary></indexterm> file is located), using .php as the ending, instead of .txt:</para><screen><![CDATA[<?php
]]><![CDATA[global $prefix, $dbi;
]]><![CDATA[include_once("mainfile.php");
]]><![CDATA[$url_downloads_folder = "http://www.humpa.com/images/"; // put the url to the
]]><![CDATA[ // directory with your downloads - you need the trailing slash!
]]><![CDATA[$cat = 2; // the download category id (cid)
]]><![CDATA[$description = "You can put a generic description here - this will be on all of them!!!!";
]]><![CDATA[$name = "PutThe_Subbmitted_By_Name_Here";
]]><![CDATA[$email = "PutEmailHere";
]]><![CDATA[$the_hits = 0; // you can change this if you want
]]><![CDATA[$filesize = 0; // you can change this if you want
]]><![CDATA[$version = ""; // you can put something betwenn the quotes if you want, or leave them empty
]]><![CDATA[$homepage = "http://www.HomePage.com";
]]><![CDATA[$fp = @fopen("$url_downloads_folder","r");
]]><![CDATA[if($fp) {
]]><![CDATA[ echo "success opening the $url_downloads$downloads_folder folder.<br><br>";
]]><![CDATA[
]]><![CDATA[ $i=1;
]]><![CDATA[ $buffer = "";
]]><![CDATA[ while (!feof ($fp)) {
]]><![CDATA[ $i++;
]]><![CDATA[ $buffer_temp = fgets($fp, 2048);
]]><![CDATA[ $buffer = "$buffer$buffer_temp";
]]><![CDATA[ }
]]><![CDATA[fclose ($fp);
]]><![CDATA[}else {
]]><![CDATA[ echo "couldn't connect to $url_downloads_folder";
]]><![CDATA[ die();
]]><![CDATA[}
]]><![CDATA[//$buffer = str_replace("A HREF=\"/", "", $buffer);
]]><![CDATA[//$buffer = str_replace("A HREF=\"?", "", $buffer);
]]><![CDATA[$i=0;
]]><![CDATA[while(eregi("(<A HREF=\")([a-zA-Z0-9._-]+)(\">)",$buffer,$array_data)) {
]]><![CDATA[ $i++;
]]><![CDATA[ $buffer = str_replace($array_data[1].$array_data[2].$array_data[3],"",$buffer);
]]><![CDATA[ //echo "$array_data[2] is data-2<br>";
]]><![CDATA[ $file_names[$i] = $array_data[2];
]]><![CDATA[}
]]><![CDATA[echo "found $i files<br>";
]]><![CDATA[while($i>0) {
]]><![CDATA[ //echo "$file_names[$i]<br>";
]]><![CDATA[ $title = eregi_replace("(.+)(\.)(.+)","\\1",$file_names[$i]);
]]><![CDATA[ $url = $url_downloads_folder.$file_names[$i];
]]><![CDATA[ $the_sql_querys .= "insert into ".$prefix."_downloads_downloads values
]]><![CDATA[(NULL, '$cat', '0', '$title', '$url', '$description', now(), '$name', '$email',
]]><![CDATA['$the_hits',",'0','0','0', '$filesize', '$version', '$homepage');<br><br>";
]]><![CDATA[ $i--;
]]><![CDATA[}
]]><![CDATA[echo "<br><br>$the_sql_querys";
]]><![CDATA[?>
]]></screen><para>You must of course adapt the script to your situation. The following variables must be set correctly:</para><itemizedlist><listitem><para>$url_downloads_folder: the url to the directory with your downloads - you need the trailing slash (obligatory)!</para></listitem><listitem><para>$cat: the download category id (cid) (obligatory).</para></listitem><listitem><para>$description: you can put a generic description here - this will be on all of them! (optional)</para></listitem><listitem><para>$name: this will be the Subbmitted_By name (optional).</para></listitem><listitem><para>$email : your email (optional).</para></listitem><listitem><para>$version: the download version (optional).</para></listitem><listitem><para>$homepage:<indexterm><primary>homepage</primary></indexterm> your homepage address (optional).</para></listitem></itemizedlist><para>When you point the browser to the locally saved downloadadd.php script, it will print out some messages about the files it found in your downloads<indexterm><primary>ads</primary></indexterm> folder and also all the necessary SQL INSERT commands for those files to be entered as Downloads in the Downloads module.<indexterm><primary>module</primary></indexterm> </para><caution>
<title>
You should not have a file named index.html in your downloads folder!
</title>
<para>
If you have an index.html, index.htm or similar file in the $url_downloads_folder, the script will analyze the contents of this file, instead of the contents of the folder itself! Thus, to get the right SQL INSERT commands, you should make sure that your download folder does not contain any index.htm* file.
</para>
</caution>
<para>You can copy and paste them in a text file, call it downloads.<indexterm><primary>ads</primary></indexterm>sql for example, then run that file in the MySQL prompt, just as we did with the dmoz.sql<indexterm><primary>dmoz.sql</primary></indexterm> file in <xref linkend="enter-thousands-of-web-links">:</para><screen><![CDATA[mysql < downloads.sql
]]></screen><tip>
<title>
Test a few INSERTSs first!
</title>
<para>
You should copy and test a few INSERTs first, before you run the whole downloads.sql file! You might not be satisfied with the resulted entries, you might discover an error, or decide to change some optional variable in the script - all this is much easier if you just tested a few commands first!
</para>
</tip>
<para>See <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=12191">How to add many downloads to my phpnuke site?</ulink>, <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=13545">Question about bulk upload</ulink> and <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=13525">Can this be done?</ulink>.</para></sect1>
<sect1 id="check-validity-of-web-links"><title>How to check the validity of thousands of web links</title><para>
<figure id="fig-weblinks-3">
<title>
Administration panel: Web Links.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1196;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1196;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1196;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1196;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Web Links.</phrase>
</textobject>
<caption>
<para>Administration panel: Web Links.</para>
</caption>
</mediaobject>
</figure>
</para><para>Problem: You need the check the validity of your <application>PHP-Nuke</application> weblinks. You have a lot of them and the built-in checker of <application>PHP-Nuke</application> just hangs <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_frown.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_frown.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_frown.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_frown.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject>, probably due to constraints on <acronym>CPU</acronym> time consumption (usually 30 sec.) . You would like to run a cron job to check for valid weblinks.</para>
<para>Solution: Download <ulink url="http://dlc.sourceforge.net">deadlinkcheck</ulink>, let MySQL dump a list of your web links, and give it to deadlinkcheck<indexterm><primary>deadlinkcheck</primary></indexterm> to validate (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=9">How to check the validity of thousands of weblinks</ulink>, <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=14137">Weblinks Validation</ulink>). </para><para>deadlinkcheck is a simple - you guessed right! - dead link checker.<indexterm><primary>checker</primary></indexterm> It only requires <application>Perl</application> 5.x to run, nothing else. It produces a nice HTML validation report that you can check every day, if you combine it with a scheduling facility like cron.<indexterm><primary>cron</primary></indexterm> To install it, follow these three simple steps:<indexterm><primary>steps</primary></indexterm></para><orderedlist><listitem><para><indexterm><primary>Enumerate</primary></indexterm>Extract the tar archive you downloaded:</para><screen><![CDATA[tar -xzvf dlc-0.4.0.tar.gz
]]></screen></listitem><listitem><para>Change in the newly created directory dlc-0.4.0 and run the configure script:</para><screen><![CDATA[./configure --prefix=/usr/local
]]></screen><para>Substitute your own prefix.<indexterm><primary>prefix</primary></indexterm> In the above example, deadlinkcheck will be installed in /usr/local/bin and the man page in /usr/local/man/man1 (unfortunately, the --mandir option to the configure script is not honoured).</para></listitem><listitem><para><indexterm><primary>Enumerate</primary></indexterm>Run &quot;make install&quot;. This completes installation.<indexterm><primary>installation</primary></indexterm> Do a &quot;man deadlinkcheck&quot; to get acquainted with the options.</para></listitem></orderedlist><para>The only thing you need now, is a file with all those 5000 HTTP links - or were they 50000? <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> No matter how many links you have to check, this is easy done:</para>
<para>Create a MySQL batch script, say weblinks.<indexterm><primary>weblinks</primary></indexterm>sql, that contains:</para><screen><![CDATA[# Put your database here!
]]><![CDATA[use phpnuke;
]]><![CDATA[#
]]><![CDATA[# Output all entries of 'nuke_weblinks'
]]><![CDATA[#
]]><![CDATA[select url from nuke_links_links;
]]></screen><para>Run it from the MySQL prompt:</para><screen><![CDATA[mysql < weblinks.sql
]]></screen><para>(You may need to add your user and password in the file, see <ulink url="http://www.mysql.com/doc/en/Batch_mode.html">running MySQL in Batch Mode</ulink>). This should produce a list of all the URLs on the standard output. You only need to redirect it to a file:</para><screen><![CDATA[mysql < weblinks.sql > urls_weblinks
]]></screen><para>Now all the above comes to its completion: write a cron job to execute a script that contains the following two commands:</para><screen><![CDATA[mysql < weblinks.sql > urls_weblinks
]]><![CDATA[deadlinkcheck -output deadlinks.html -HTMLoutput urls_weblinks
]]></screen><para>Next day, when the cron job is finished and you're enjoying the morning coffee, just open the file deadlinks.html with your browser and check the results.<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_smile.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_smile.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_smile.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_smile.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject></para>
<tip>
<title>
How to find out the category of the invalid links
</title>
<para>
To find and correct an invalid link in PHP-Nuke, it is nice to know the category it is in. The solution we will present is not perfect, but you could find an even better one, if you were willing to tweak the code of the deadlinkcheck script. Use the following command in weblinks.sql:
</para>
<screen>
<![CDATA[select url, cid, sid from nuke_links_links;]]>
</screen>
<para>
The rest remains the same. Now, at the end you get a file that contains the validated links, sorted according to HTTP return code (2xx, 3xx and 4xx) with the difference that now you see the categories in the anchor text! The links themselves show up in the status line of the browser when you pass the mouse pointer over the category id! This just makes use of a bug (in this case a feature
<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject>
) of deadlinkcheck: if you have more information than just the link to check on a line, it checks the link and uses (part of) that extra information as anchor text.
</para>
</tip>
</sect1>
<sect1 id="enter-thousands-of-ephemerids"><title>How to enter thousands of ephemerids</title><para>
<figure id="fig-ephemerids-2">
<title>
Administration panel: Ephemerids.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1197;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1197;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1197;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1197;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Ephemerids.</phrase>
</textobject>
<caption>
<para>Administration panel: Ephemerids.</para>
</caption>
</mediaobject>
</figure>
</para><para>Problem: You have a file of nice quotes (often called &quot;fortunes&quot;) that you would like to see displayed every day in the Ephemerids module (see <xref linkend="preinstalled-modules"> for the user view and <xref linkend="administration-functions"> for the administrator view of the Ephemerids module) . You don't want to write all those texts by hand, so you are looking for a way to automate the text insertion.<indexterm><primary>insertion</primary></indexterm></para><para>Idea:The right command to insert a text in the Ephemerids table nuke_ephem<indexterm><primary>nuke_ephem</primary></indexterm> is:</para><screen><![CDATA[insert into nuke_ephem values (4,4,11,2002,
]]><![CDATA["Nothing cures insomnia like the realization that it's time to get up.",");
]]></screen><para>We will use a script to produce these INSERT commands (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=5">Inserting Ephemerids through script</ulink>).</para><para>Solution: We write a script like:</para><screen><![CDATA[#! /bin/sh
]]><![CDATA[did=6
]]><![CDATA[while [ $did -le 30 ]; do
]]><![CDATA[ read LINE
]]><![CDATA[ if [ -n "$LINE" ]; then
]]><![CDATA[ echo "insert into nuke_ephem values (",$did,11,2002,\"$LINE\",");"
]]><![CDATA[ did=$((did+1))
]]><![CDATA[ fi
]]><![CDATA[done
]]></screen><para>Let's call it &quot;ephemerids&quot;<indexterm><primary>ephemerids</primary></indexterm> - don't forget to make it executable. When executed, the ephemerids script outputs the MySQL INSERT command we saw above, for each fortune in the standard input. Suppose that the &quot;fortunes&quot; are in the file called &quot;myfortune&quot;<indexterm><primary>myfortune</primary></indexterm>, one fortune per line. Then, if you use the script as follows:</para><screen><![CDATA[ephemerids < myfortune > ephemerids.sql
]]></screen><para>it will create the necessary MySQL statements and put them all in the ephemerids.<indexterm><primary>ephemerids</primary></indexterm>sql file. Once ephemerids.<indexterm><primary>ephemerids</primary></indexterm>sql is created, you only need to import it in the <application>PHP-Nuke</application> database.<indexterm><primary>base</primary></indexterm> For this, you can type</para><screen><![CDATA[mysql -u dbuname -h dbhost -p dbname < ephemerids.sql
]]></screen><para>or use the import function of phpMyAdmin (<xref linkend="phpmyadmin">).</para><para>Verification: To show the content of nuke_ephem and verify that the fortunes were inserted, execute the following SQL query:<indexterm><primary>query</primary></indexterm></para><screen><![CDATA[select eid,did,mid,yid from nuke_ephem;
]]></screen><para>Note that in this version, the above problem can be easily solved with the Random Quotes block (see <xref linkend="PHP-Nuke-Random-Quotes-block">). However, instead of fortunes, you could just as well have the birthdays of hundreds of people, or the dates and descriptions of thousands of historical events, as in a classic ephemerids context.<indexterm><primary>context</primary></indexterm></para></sect1>
<sect1 id="make-encyclopedia-international"><title>How to make the Encyclopedia international</title><para>
<figure id="fig-encyclopedia-2">
<title>
Administration panel: Encyclopedia.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1198;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1198;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1198;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1198;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Encyclopedia.</phrase>
</textobject>
<caption>
<para>Administration panel: Encyclopedia.</para>
</caption>
</mediaobject>
</figure>
</para><para>If you are using the Encyclopedia module in your own language, which happens to be different from english, you may encounter problems like the following:</para><itemizedlist><listitem><para>If you enter a term in your language, it is not recognized, if you enter it in english, it is.</para></listitem><listitem><para>Sorting of Encyclopedia terms is O.K. for english terms,<indexterm><primary>terms</primary></indexterm> but not O.K. for terms in your language.</para></listitem></itemizedlist><para>Such problems have their roots in both MySQL and the Encyclopedia code (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=204">Encyclopedia Module with terms in non-english language</ulink>):</para><para>First, make sure that the MySQL server uses the right character encoding.<indexterm><primary>encoding</primary></indexterm> From the MySQL manual on <ulink url="http://www.mysql.com/doc/en/Character_sets.html">The Character Set Used for Data and Sorting</ulink>:</para><blockquote><para>By default, MySQL uses the ISO-8859-1 (Latin1) character set with sorting<indexterm><primary>sorting</primary></indexterm> according to Swedish/Finnish. This is the character set suitable in the USA and western Europe.<indexterm><primary>Europe</primary></indexterm></para><para>All standard MySQL binaries are compiled with --with-extra-charsets=complex. This will add code to all standard programs to be able to handle latin1<indexterm><primary>latin1</primary></indexterm> and all multi-byte character sets within the binary. Other character sets will be loaded from a character-set definition file when needed.</para><para>The character set determines what characters are allowed in names and how things are sorted by the ORDER BY and GROUP BY clauses of the SELECT statement.</para><para>You can change the character set with the --default-character-set option when you start the server.<indexterm><primary>server</primary></indexterm> The character sets available depend on the --with-charset=charset and --with-extra-charsets= list-of-charset | complex | all | none options to configure, and the character set configuration files listed in `SHAREDIR/charsets/Index'.</para></blockquote><para>Also, the user comments for the <ulink url="http://www.mysql.com/doc/en/German_character_set.html">German character set in MySQL</ulink> suggest that, if you change the default character encoding of mysqldd <emphasis>after</emphasis> you have already entered some texts with a different character set previously, then you will have to export the database and reimport it, for all texts to be stored with the right character encoding.<indexterm><primary>encoding</primary></indexterm> &quot;REPAIR&quot;<indexterm><primary>REPAIR</primary></indexterm> or &quot;MYISAMCHECK&quot; (see <xref linkend="repair-corrupt-table">) will not help, even if the documentation wants to make us believe they will. </para><para>You can see the character set used in a table by issuing the command<indexterm><primary>command</primary></indexterm></para><screen><![CDATA[myisamchk -dvv table.MYI
]]></screen><para>If it is not the one you want, then the only thing that helps is to export<indexterm><primary>export</primary></indexterm> the DB and reimport it with:</para><screen><![CDATA[mysqldump -u dbuname -h dbhost --all-databases --add-drop-table -p dbname > backup.sql
]]></screen><para>for the export,<indexterm><primary>export</primary></indexterm> and </para><screen><![CDATA[mysql -u dbuname -h dbhost -lL -p dbname < backup.sql
]]></screen><para>for the import, where dbuname,<indexterm><primary>dbuname</primary></indexterm> dbhost and dbname are exactly the same as in your config.<indexterm><primary>config</primary></indexterm>php (<xref linkend="config-php-file">). Your character encoding should be set to the one that is aproppriate for your language, see the <ulink url="http://www.mysql.com/doc/en/Charset-map.html">Table with Character Sets and Corresponding 4.1 Character Set/Collation Pairs</ulink>.</para><para>Second, even if you set the character encoding correctly in MySQL,<indexterm><primary>MySQL</primary></indexterm> you may still want to change the $alphabet array in the alpha() function of modules/Encyclopedia/index.php:<indexterm><primary>index.php</primary></indexterm></para><screen><![CDATA[$alphabet = array ("A","B","C","D","E","F","G","H","I","J","K","L","M",
]]><![CDATA["N","O","P","Q","R","S","T","U","V","W","X","Y","Z");
]]></screen><para>Add the letters of your non-english alphabet there, either by intermixing them with the english ones, or by deleting the english ones alltogether.</para><para>The way all this works in PHP-Nuke, is by constructing a database query<indexterm><primary>query</primary></indexterm> that finds all entries of the given encyclopedia id having a title which, when transformed to all uppercase,<indexterm><primary>case</primary></indexterm> starts &quot;like&quot; the given letter, where the letter can only be one of the entries in the $alphabet array. See for yourself in function terms() of modules/Encyclopedia/index.php:<indexterm><primary>index.php</primary></indexterm></para><screen><![CDATA[$sql = "SELECT tid, title FROM ".$prefix."_encyclopedia_text
]]><![CDATA[WHERE UPPER(title) LIKE '$ltr%' AND eid='$eid'";
]]></screen><para>Now, what if you want to mix chinese and greek together? <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
<para>In such a case, your best bet would be to go with Unicode.<indexterm><primary>Unicode</primary></indexterm> But given that <ulink url="http://www.php.net/manual/en/language.types.string.php">PHP's Unicode support is close to non-existent</ulink>, you are out of luck. Perhaps this will change in the future. In the meantime, you can prepare yourself with a good reading on <ulink url="http://www.joelonsoftware.com/articles/Unicode.html">The Absolute Minimum Every Software Developer Absolutely, Positively Must Know About Unicode and Character Sets</ulink> - No Excuses!</para></sect1>
<sect1 id="find-user-name"><title>How to find the user name in a module</title><para>If you want to greet the user personally, if registered,<indexterm><primary>registered</primary></indexterm> from your own home-made module,<indexterm><primary>module</primary></indexterm> here is the code that does it in <application>PHP-Nuke</application> (see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=13404">Getting username in <acronym>PHP</acronym> script</ulink>):</para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[if (!isset($mainfile)) {include("mainfile.php"); }
]]><![CDATA[include ("header.php");
]]><![CDATA[if(!is_array($user)) {
]]><![CDATA[ $user_get = base64_decode($user);
]]><![CDATA[ $user_get = explode(":", $user_get);
]]><![CDATA[ $user_name = "$user_get[1]";
]]><![CDATA[} else {
]]><![CDATA[ $user_name = "$user[1]";
]]><![CDATA[}
]]><![CDATA[if($user_name == "") {$user_name="Anonymous";}
]]><![CDATA[echo "Welcome, $user_name";
]]><![CDATA[include ("footer.php");
]]><![CDATA[
]]><![CDATA[?>
]]><![CDATA[
]]></screen></sect1>
<sect1 id="correct-thousands-of-users-fields"><title>How to correct thousands of users fields</title><para>You have discovered a problem where several (thousands) of your users were added through the edit user screen and ended up with a space (or in some cases 2 spaces) inserted before the e-mail address and other fields. Your bulk e-mails are coming through, but you are not able to effectively search or sort users because of this space.<indexterm><primary>space</primary></indexterm> In situations like this, you must be able to correct thousands of users fields, without having to do it manually. Proceed as follows (see <ulink url="http://www.nukeforums.com/forums/viewtopic.php?t=18469">exporting nuke_users data</ulink>):</para><para>Create the following <acronym>PHP</acronym> script with a <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=122">decent text editor</ulink> (<xref linkend="editing-PHP-Nuke-files">):</para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[include("mainfile.php");
]]><![CDATA[global $prefix, $db, $dbi;
]]><![CDATA[
]]><![CDATA[$sql = "SELECT * FROM ".$prefix."_users ORDER BY user_id ASC";
]]><![CDATA[$result = $db->sql_query($sql);
]]><![CDATA[
]]><![CDATA[while ($row = $db->sql_fetchrow($result)) {
]]><![CDATA[ $userid = $row['user_id'];
]]><![CDATA[ $oldemail = $row["user_email"];
]]><![CDATA[ $newemail = str_replace (" ","",$oldemail);
]]><![CDATA[ $update = $db->sql_query("UPDATE ".$prefix.
]]><![CDATA[ "_users set user_email='$newemail' where user_id='$userid'");
]]><![CDATA[}
]]><![CDATA[
]]><![CDATA[?>
]]></screen><para>Upload it in the same directory where also the mainfile.php of your <application>PHP-Nuke</application> is located (sinse it includes mainfile.php with a relative, as opposed to absolute, path, it will not work if you upload it in a different place!). Point your browser to it - and the script will do the rest for you! <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_cool.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_cool.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_cool.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_cool.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject></para>
<caution>
<title>
Backup your database!
</title>
<para>
Always make a backup of your database before trying such a thing! If it breaks, you keep both pieces.
</para>
</caution>
</sect1>
<sect1 id="size-select-boxes"><title>How to size the select boxes in a module</title><para>
<figure id="fig-downloads-3">
<title>
Administration panel: Downloads.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1199;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1199;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1199;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1199;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Administration panel: Downloads.</phrase>
</textobject>
<caption>
<para>Administration panel: Downloads.</para>
</caption>
</mediaobject>
</figure>
</para><para>Select boxes (those boxes that present you with multiple options to choose from a dropdown list) are in many places around in <application>PHP-Nuke</application>. An example is the &quot;Modify a Category&quot; select box in the Downloads administration panel (<xref linkend="fig-downloads-add-download">).</para><para>
<figure id="fig-downloads-add-download">
<title>
Downloads: Add download.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1200;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1200;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1200;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1200;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Downloads: Add download.</phrase>
</textobject>
<caption>
<para>Downloads: Add download.</para>
</caption>
</mediaobject>
</figure>
</para><para>What if you wish to change the dimensions of such a select box? The code that outputs the select boxes is in admin/modules/download.<indexterm><primary>download</primary></indexterm>php. Just search the code there for &quot;&lt;select&quot; and you will see them all.</para><para>However, there is no way to manipulate the width of a select box in HTML,<indexterm><primary>HTML</primary></indexterm> other than entering a &quot;dummy&quot;<indexterm><primary>dummy</primary></indexterm> option that has a certain length: the width of a select box is determined by the width of the longest line of text beside an &lt;option&gt;! Thus, there is no way to set the width of select boxes except by manipulating the text tags associated with &lt;option&gt;s. </para><para>This leads us to the following tip (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=345">How to Change Width of Modify a Category Drop-Down</ulink>):</para><tip>
<title>
Sizing The select box in Downloads
</title>
<para>
The very first category that you ever enter in the Downloads Administration Panel should be one with a text long enough to size the box to the desired length. If you choose to enter a "dummy" category like "Choose your Category here" (see <xref linkend="fig-downloads-add-download-2">), bear in mind that it will be displayed along with the "right" ones in the Downloads category list.
</para>
</tip>
<para>
<figure id="fig-downloads-add-download-2">
<title>
Downloads: Add download.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1201;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1201;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1201;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1201;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Downloads: Add download.</phrase>
</textobject>
<caption>
<para>Downloads: Add download.</para>
</caption>
</mediaobject>
</figure>
</para></sect1>
<sect1 id="date-time"><title>How to deal with date and time</title><para>You will encounter date/time functions all over PHP-Nuke: cookie expiration<indexterm><primary>expiration</primary></indexterm> time, broadcast message duration time, article time, server time. <acronym>PHP</acronym> offers many functions that help us with date/time tasks. Here we will cover:</para><itemizedlist><listitem><para>How to find the last date of some article,<indexterm><primary>article</primary></indexterm> download etc. (<xref linkend="find-last-date">),</para></listitem><listitem><para>How to adjust server time (<xref linkend="adjust-server-time">),</para></listitem><listitem><para>How to use the Discordian Calendar (<xref linkend="Discordian-Calendar">). </para></listitem></itemizedlist><sect2 id="find-last-date"><title>How to find the last date of...</title><para>Dates are stored in many tables of <application>PHP-Nuke</application>. The date fields are used to hold the date we</para><itemizedlist><listitem><para>entered a banner and whhen that banner expires,</para></listitem><listitem><para>wrote a private message,</para></listitem><listitem><para>wrote a comment,</para></listitem><listitem><para>entered a download link,</para></listitem><listitem><para>voted for something (article,<indexterm><primary>article</primary></indexterm> download, link etc.),</para></listitem><listitem><para>wrote in our journal,</para></listitem><listitem><para>inserted a web link,</para></listitem><listitem><para>wrote a review, </para></listitem><listitem><para>wrote an article<indexterm><primary>article</primary></indexterm></para></listitem></itemizedlist><para>and so on. Sometimes, while writing a modification (<xref linkend="modifying-php-nuke-blocks">, <xref linkend="modifying-php-nuke-modules">), or even a new block (<xref linkend="blocks">) or module (<xref linkend="creating-modules">), you may want to compute the last date that an event like the above has happened.</para><para>Whenever you encounter a problem of this type - find the first, the last, the minimum, the maximum, the average...of some attribute that is stored in a table field of <application>PHP-Nuke</application> - think <ulink url="http://www.mysql.com/doc/en/GROUP-BY-Functions.html">aggregate functions</ulink>. There is no need to go through a loop of all records in our table, just to find an aggregate function of its fields - the database does it for us: <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_cool.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_cool.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_cool.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_cool.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject></para>
<screen><![CDATA[SELECT max( date ) FROM nuke_downloads_downloads;
]]></screen><para>The above SQL query will compute the maximum date (i.e. the <emphasis>last</emphasis> date) of all links n the Downloads section. You can use SQL queries like the above in your blocks and modules.<indexterm><primary>modules</primary></indexterm> To start with, create (with a <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=122">decent text editor</ulink>, see <xref linkend="editing-PHP-Nuke-files">) a file that contains (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=344">How to compute the date of the last file added in Downloads</ulink>):</para><screen><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[require_once("mainfile.php");
]]><![CDATA[global $db;
]]><![CDATA[include("header.php");
]]><![CDATA[
]]><![CDATA[$sql = "SELECT max(date) FROM nuke_downloads_downloads";
]]><![CDATA[$result = $db->sql_query($sql);
]]><![CDATA[$row = $db->sql_fetchrow($result);
]]><![CDATA[$maxdate = $row["max(date)"];
]]><![CDATA[
]]><![CDATA[echo "maxdate = $maxdate";
]]><![CDATA[echo "<br><br>";
]]><![CDATA[
]]><![CDATA[?>
]]></screen><para>name it query.php,<indexterm><primary>query.php</primary></indexterm> upload it in the same dir on your server where also mainfile.php is located, then point your browser to query.php.<indexterm><primary>query.php</primary></indexterm> You should see a line like</para><screen><![CDATA[maxdate = 2003-11-17 15:33:03
]]></screen><para>This example illustrates the use of the new SQL layer (see <xref linkend="sql-syntax">) for the computation of aggregates. Note that the argument of the $row array is a string that mimics exactly the aggregate function in the SELECT statement:</para><screen><![CDATA[$maxdate = $row["max(date)"];
]]></screen><para>Here, &ldquo;max(date)&rdquo; is just a string and has nothing to do with the max() function.<indexterm><primary>function</primary></indexterm></para><para>Of course, this example is more a &ldquo;proof of concept&rdquo;, rather than something you should use in production - on the contrary, you should delete it from server as soon as you don't need it, for security<indexterm><primary>security</primary></indexterm> reasons. But it serves as a starting point for more ambitious projects. like the following modification to the Downloads module:<indexterm><primary>module</primary></indexterm></para><para>Problem: You have various categories and subcategories defined in the Downloads<indexterm><primary>ads</primary></indexterm> section. For each category,<indexterm><primary>category</primary></indexterm> you want to compute the last date that you entered some download link, either in this category,<indexterm><primary>category</primary></indexterm> <emphasis>or in any of its subcategories<indexterm><primary>subcategories</primary></indexterm></emphasis>.</para><para>We have already seen how to find the lst date of the downloads in <emphasis>one</emphasis> category above. What makes the situation here somewhat more complicated is the fact that we have to do the same computation for every subcategory of a category<indexterm><primary>category</primary></indexterm> - however we don't know all those subcategory IDs a priori, we have to search for them.</para><para>More specifically, the steps to be taken for every category <acronym>ID</acronym> $cid are:</para><itemizedlist><listitem><para>Compute the maximum date for that $cid.<indexterm><primary>cid</primary></indexterm></para></listitem><listitem><para>Search the nuke_downloads_categories for all category IDs, whose parent<indexterm><primary>parent</primary></indexterm> <acronym>ID</acronym> is $cid.<indexterm><primary>cid</primary></indexterm> Let's call such a category <acronym>ID</acronym> $subcid (meaning that it is a subcategory,<indexterm><primary>subcategory</primary></indexterm> since it has a parent,<indexterm><primary>parent</primary></indexterm> $cid).</para></listitem><listitem><para>Compute the latest date a download was inserted in that $subcid.<indexterm><primary>cid</primary></indexterm> Do this for all $subcid's you can find for that $cid.<indexterm><primary>cid</primary></indexterm></para></listitem><listitem><para>Compute the maximum of all those maximum dates (including the maximum date<indexterm><primary>date</primary></indexterm> for $cid). This will be the latest date a download link was inserted in either the category $cid, or any of its subcategories $subcid.<indexterm><primary>cid</primary></indexterm></para></listitem></itemizedlist><para>The code that implements the above algorithm is (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=344">How to compute the date of the last file added in Downloads</ulink>):</para><screen>
<![CDATA[$sql3 = "SELECT max(date) FROM ".$prefix."_downloads_downloads WHERE cid='$cid'";]]> <co id="maxdate1">
<![CDATA[$result3 = $db->sql_query($sql3);]]>
<![CDATA[$row3 = $db->sql_fetchrow($result3);]]>
<![CDATA[$maxdate3 = $row3["max(date)"];]]> <co id="maxdate2">
<![CDATA[]]>
<![CDATA[$sql4 = "SELECT cid FROM ".$prefix."_downloads_categories WHERE parentid='$cid'";]]> <co id="maxdate3">
<![CDATA[$result4 = $db->sql_query($sql4);]]>
<![CDATA[$maxdate4 = 0;]]>
<![CDATA[while ($row4 = $db->sql_fetchrow($result4)) {]]> <co id="maxdate4">
<![CDATA[ $subcid = $row4["cid"];]]>
<![CDATA[ $sql5 = "SELECT max(date) FROM ".$prefix."_downloads_downloads WHERE cid='$subcid'";]]> <co id="maxdate5">
<![CDATA[ $result5 = $db->sql_query($sql5);]]>
<![CDATA[ $row5 = $db->sql_fetchrow($result5);]]>
<![CDATA[ $maxdate5 = $row5["max(date)"];]]> <co id="maxdate6">
<![CDATA[ if ($maxdate5 > $maxdate4){]]>
<![CDATA[ $maxdate4 = $maxdate5;]]> <co id="maxdate7">
<![CDATA[ }]]>
<![CDATA[}]]>
<![CDATA[]]>
<![CDATA[$maxdate = max($maxdate3, $maxdate4);]]> <co id="maxdate8">
<![CDATA[if ($maxdate) {]]>
<![CDATA[ echo "<font class=\"content\">Latest Download on $maxdate</font><br>";]]> <co id="maxdate9">
<![CDATA[}]]>
</screen>
<calloutlist>
<callout arearefs="maxdate1">
<para>
Compute the maximum date for that $cid. The SQL query is the same as the one we used in the simplified example above.
</para>
</callout>
<callout arearefs="maxdate2">
<para>
This is the maximum date for the category <acronym>ID</acronym> $cid. It may or may not be set, depending on whether we entered a download directly under that category at all, i.e. without making use of any of its subcategories. If we did, this is the last date (and time) we did it, otherwise it is 0.
</para>
</callout>
<callout arearefs="maxdate3">
<para>
With this SQL query, we select all subcategories of that category. The subcategories' parentid field will contain the parent category ID, therefore this field must be equal to our $cid.
</para>
</callout>
<callout arearefs="maxdate4">
<para>
We enter a loop for every subcategory. Inside the loop, the subcategory will be stored in $subcid and we will compute the maximum date for each subcategory <acronym>ID</acronym>.
</para>
</callout>
<callout arearefs="maxdate5">
<para>
This is the same SQL query we used previously to compute the maximum date for a given <acronym>ID</acronym>. In this case, the <acronym>ID</acronym> is that one of the subcategory, i.e. $subcid. Depending on whether we entered a download under that subcategory this will either be the last date (and time) we did so, or just 0.
</para>
</callout>
<callout arearefs="maxdate6">
<para>
The maximum date of downloads under the $subcid is stored in $maxdate5.
</para>
</callout>
<callout arearefs="maxdate7">
<para>
Since for every subcategory $subcid, a different maximum date is going to be stored in $maxdate5, we have to compute the maximum of all those maximums. This is stored in $maxdate4. At the end of the loop, $maxdate4 will be the maximum of all dates of all subcategories. Again, this will be some date, or zero.
</para>
</callout>
<callout arearefs="maxdate8">
<para>
Finally, we take the maximum of the maximum date of all subcategories and the maximum date of the category itself. This is the last date we inserted a link, either in the category itself, or in any of its subcategories.
</para>
</callout>
<callout arearefs="maxdate9">
<para>
Print some result, if the last date we computed is not 0. It looks as in <xref linkend="fig-downloads-main-categories-maxdate">.
</para>
</callout>
</calloutlist>
<para>
<figure id="fig-downloads-main-categories-maxdate">
<title>
Downloads: Main categories with last download date.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1202;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1202;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1202;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1202;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Downloads: Main categories with last download date.</phrase>
</textobject>
<caption>
<para>Downloads: Main categories with last download date.</para>
</caption>
</mediaobject>
</figure>
</para><tip>
<title>
Use JOIN
</title>
<para>
This algorithm would be a perfect example of an application of the SQL JOIN query, since the &ldquo;parent-child&rdquo; information is kept in a different table, nuke_downloads_categories, while the dates themselves are kept in nuke_downloads_downloads. However, JOINs may not be supported by your version of MySQL, so we took the rather primitive (and usually slower) approach of nested SELECT statements in the code above. If you only have a few categories, subcategories and downloads, JOINs may not be a big deal for you, but the situation changes if you have thousands of them (see <xref linkend="enter-thousands-of-download-links"> on how you can enter that many, without subjecting yourself to <ulink url="http://freshmeat.net/articles/view/407/">Repetitive Stress Injury</ulink> <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject>). You are encouraged to experiment with JOINs and test if they improve the algorithm's performance!
</para>
</tip>
</sect2>
<sect2 id="adjust-server-time"><title>How to adjust server time</title><para>
<figure id="fig-your-info-profile-timezone">
<title>
Your Info profile: Timezone and Date settings.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1203;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1203;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1203;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1203;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>Your Info profile: Timezone and Date settings.</phrase>
</textobject>
<caption>
<para>Your Info profile: Timezone and Date settings.</para>
</caption>
</mediaobject>
</figure>
</para><para>In some cases, perhaps due a misconfiguration of your server,<indexterm><primary>server</primary></indexterm> the time shown up in the News stories is wrong. Normally, it should be possible to control it by changing the time settings<indexterm><primary>settings</primary></indexterm> in either the Preferences of the administration panel,<indexterm><primary>panel</primary></indexterm> or the user preferences (<xref linkend="fig-your-info-profile-timezone">). However, there will be situations where a quick fix is desirable. </para><para>You can offset the time by tweaking the following line in the mainfile.php<indexterm><primary>mainfile.php</primary></indexterm> in the function formatTimeStamp (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=410">How to adjust server time in PHP-Nuke</ulink>):</para><screen><![CDATA[$datetime = strftime(""._DATESTRING."", mktime($datetime[4],$datetime[5],$datetime[6],
]]><![CDATA[$datetime[2],$datetime[3],$datetime[1]));
]]></screen><para>For example to add one hour (3600 seconds), you would simply add 3600:<indexterm><primary>600</primary></indexterm></para><screen><![CDATA[$datetime = strftime(""._DATESTRING."", mktime($datetime[4],$datetime[5],$datetime[6],
]]><![CDATA[$datetime[2],$datetime[3],$datetime[1]) + 3600);
]]></screen><para>or, to subtract two hours:<indexterm><primary>hours</primary></indexterm></para><screen><![CDATA[$datetime = strftime(""._DATESTRING."", mktime($datetime[4],$datetime[5],$datetime[6],
]]><![CDATA[$datetime[2],$datetime[3],$datetime[1]) - 7200);
]]></screen><para>A situation that calls for server time modification arises when your server<indexterm><primary>server</primary></indexterm> is located in a different timezone than your geographic location - say you are located in Japan, but your hosting company is in Canada (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=410">How to adjust server time in PHP-Nuke</ulink>). The article on phpbuilder.com <ulink url="http://phpbuilder.com/columns/ehresman20030911.php3">On User-Defined Timezones in PHP</ulink> explains the problem in detail. Quoting:</para><blockquote><para>PHP's 'mktime' and 'date' functions work well as a pair without the help of any other timestamp manipulation routines, but only if the application<indexterm><primary>application</primary></indexterm> in which they are used is concerned solely with display and entry of time in the servers timezone.<indexterm><primary>timezone</primary></indexterm> If an application needs to handle entry from a timezone other than that in which the server is located something more than 'mktime' and 'date' is required.</para><para>Two things are required to accomplish this: a location independent format<indexterm><primary>format</primary></indexterm> for storing time in the database,<indexterm><primary>base</primary></indexterm> and methods to translate to and from that format into the user's local time.<indexterm><primary>local time</primary></indexterm></para></blockquote><para>Read the original article for a solution. To apply it to PHP-Nuke, you would need to replace the time functions with the new ones, read the time offset from the user's profile and display the result.</para><para>To reflect the new time zone that may be implied by the hardcoded time offset,<indexterm><primary>offset</primary></indexterm> you would also want to change the _DATESTRING definition in your language file, e.g. language/lang-english.php:<indexterm><primary>lang-english.php</primary></indexterm></para><screen><![CDATA[define("_DATESTRING","%A, %B %d @ %T %Z");
]]></screen><para>You can change the &quot;%A,<indexterm><primary>%A</primary></indexterm> %B %d @ %T %Z&quot; string to whatever you deem appropriate. <acronym>PHP</acronym> gives to some placeholders a special meaning:</para><itemizedlist><listitem><para>%a - abbreviated weekday name according to the current locale</para></listitem><listitem><para>%A - full weekday name according to the current locale</para></listitem><listitem><para>%b - abbreviated month name according to the current locale</para></listitem><listitem><para>%B - full month name according to the current locale</para></listitem><listitem><para>%c - preferred date and time representation for the current locale</para></listitem><listitem><para>%C - century number (the year divided by 100 and truncated to an integer,<indexterm><primary>integer</primary></indexterm> range 00 to 99)</para></listitem><listitem><para>%d - day of the month as a decimal number (range 01 to 31)</para></listitem><listitem><para>%D - same as %m/%d/%y<indexterm><primary>%y</primary></indexterm></para></listitem><listitem><para>%e - day of the month as a decimal number, a single digit is preceded by a space (range ' 1' to '31')</para></listitem><listitem><para>%g - like %G,<indexterm><primary>%G</primary></indexterm> but without the century.</para></listitem><listitem><para>%G - The 4-digit year corresponding to the ISO week number (see %V). This has the same format and value as %Y,<indexterm><primary>%Y</primary></indexterm> except that if the ISO week number belongs to the previous or next year, that year is used instead.</para></listitem><listitem><para>%h - same as %b</para></listitem><listitem><para>%H - hour as a decimal number using a 24-hour clock (range 00 to 23)</para></listitem><listitem><para>%I - hour as a decimal number using a 12-hour clock (range 01 to 12)</para></listitem><listitem><para>%j - day of the year as a decimal number (range 001 to 366)</para></listitem><listitem><para>%m - month as a decimal number (range 01 to 12)</para></listitem><listitem><para>%M - minute as a decimal number</para></listitem><listitem><para>%n - newline character<indexterm><primary>character</primary></indexterm></para></listitem><listitem><para>%p - either `am' or `pm' according to the given time value, or the corresponding strings for the current locale</para></listitem><listitem><para>%r - time in a.m. and p.m. notation<indexterm><primary>notation</primary></indexterm></para></listitem><listitem><para>%R - time in 24 hour notation<indexterm><primary>notation</primary></indexterm></para></listitem><listitem><para>%S - second as a decimal number</para></listitem><listitem><para>%t - tab character<indexterm><primary>character</primary></indexterm></para></listitem><listitem><para>%T - current time, equal to %H:<indexterm><primary>%H</primary></indexterm>%M:%S</para></listitem><listitem><para>%u - weekday as a decimal number [1,7], with 1 representing Monday</para></listitem><listitem><para>%U - week number of the current year as a decimal number, starting with the first Sunday as the first day of the first week</para></listitem><listitem><para>%V - The ISO 8601:1988 week number of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the current year, and with Monday as the first day of the week. (Use %G or %g for the year component that corresponds to the week number for the specified timestamp.<indexterm><primary>timestamp</primary></indexterm>)</para></listitem><listitem><para>%W - week number of the current year as a decimal number, starting with the first Monday as the first day of the first week</para></listitem><listitem><para>%w - day of the week as a decimal, Sunday being 0</para></listitem><listitem><para>%x - preferred date representation for the current locale without the time</para></listitem><listitem><para>%X - preferred time representation for the current locale without the date<indexterm><primary>date</primary></indexterm></para></listitem><listitem><para>%y - year as a decimal number without a century (range 00 to 99)</para></listitem><listitem><para>%Y - year as a decimal number including the century</para></listitem><listitem><para>%Z - time zone or name or abbreviation<indexterm><primary>abbreviation</primary></indexterm></para></listitem><listitem><para>%% - a literal `%' character<indexterm><primary>character</primary></indexterm></para></listitem></itemizedlist><para>You can combine them with punctuation or extra words to construct the datetime string of your liking. You are not limited to the above interpretation.<indexterm><primary>interpretation</primary></indexterm> For example, you can just delete the %Z,<indexterm><primary>%Z</primary></indexterm> and replace it with EST or whatever you time zone is (if you cannot set it from the preferences,<indexterm><primary>preferences</primary></indexterm> that is). There are some points to bear in mind while experimenting:</para><itemizedlist><listitem><para>Given a 'bare number' in seconds,<indexterm><primary>seconds</primary></indexterm> e.g. 143567, strftime() will format this number according to your local timezone<indexterm><primary>timezone</primary></indexterm>. Thus, for Germany, you will get an extra hour, since CET is GMT +1. If you are interested in simply formatting a number to give you hours,<indexterm><primary>hours</primary></indexterm> minutes and seconds (very quick for showing time values), then you should always use 'gmstrftime' instead, which will not adjust the time for your local timezone.<indexterm><primary>timezone</primary></indexterm> You set the local timezone in the preferences section of the administration<indexterm><primary>administration</primary></indexterm> panel, or the preferences in the user info panel.<indexterm><primary>panel</primary></indexterm> Valid timezone codes can (usually) be seen (on Linux,<indexterm><primary>Linux</primary></indexterm> at least) in /usr/share/zoneinfo or /usr/lib/zoneinfo (according to the tzset manpage).</para></listitem><listitem><para>The call to mktime</para><screen><![CDATA[mktime($datetime[4],$datetime[5],$datetime[6],$datetime[2],$datetime[3],$datetime[1])
]]></screen><para>means something equivalent to </para><screen><![CDATA[mktime($hour,$minute,$second,$month,$day,$year)
]]></screen><para>assuming that $hour, $minute etc. are filled with the right values (this is exactly what the datetime array does for us).</para></listitem></itemizedlist><para>See the <ulink url="http://www.php.net/manual/en/function.strftime.php">PHP manual page for strftime</ulink> for more information and examples about date string formatting.</para></sect2>
<sect2 id="Discordian-Calendar"><title>The Discordian Calendar</title><para>Date and time functions in <acronym>PHP</acronym> are very flexible, but I still have to find a <acronym>PHP</acronym> function that converts my date strings to the <ulink url="http://www.lojban.org/wiki/index.php/Discordian%20Calendar">Discordian Calendar</ulink>:</para><blockquote><para>The Discordian calendar divides the year into five seasons (commonly known as Chaos (la kalsa), Discord (la tolsarxe), Confusion (la cfipu), Bureaucracy<indexterm><primary>Bureaucracy</primary></indexterm> (la lujycatni) and the Aftermath (la jalge) ) of 73 days each. Every four years, an extra day (St. Tib's Day / la tib noi vrude) is inserted between Chaos 59 and Chaos 60.</para><para>The Discordian calendar defines a week as having five days, named Sweetmorn(la titcer), Boomtime (la bumtem), Pungenday (la pynjdei/cpinydei), Prickle-Prickle<indexterm><primary>Prickle-Prickle</primary></indexterm> (la kilkil) and Setting Orange (after the Five Elements). Chaos 1 is always Sweetmorn, Chaos 2 Boomtime, The Aftermath 73 Setting Orange(la canci narju), etc. St. Tib's Day is none of the five days of the week. </para><para>The Discordian calendar's year 0 (notionally the time of the Original Snub) is known in the Gregorian calendar as 1166 BC; alternatively, the Gregorian<indexterm><primary>Gregorian</primary></indexterm> year 0 (notionally the birth of the Jewish mystic Yeshua ben Yosef) is known as 1166 YOLD in the Discordian calendar.<indexterm><primary>calendar</primary></indexterm> The year known in the Gregorian calendar as 2001 is known as 3167 in the Discordian calendar.<indexterm><primary>calendar</primary></indexterm></para></blockquote><para>Just in case you wanted to know. <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
<para>How do we output a date string in the Discordian Calendar?<indexterm><primary>Calendar</primary></indexterm> If you want to write your own <acronym>PHP</acronym> ddate function,<indexterm><primary>function</primary></indexterm> you might find the code of the <ulink url="http://search.cpan.org/author/RBOW/Date-Discordian-1.36/lib/Date/Discordian.pm">Perl Date::Discordian module</ulink> useful. If the settings in your php.ini allow the execution of system commands (either safe_mode is off, or safe_mode is on and safe_mode_exec_dir contains the directory that holds the ddate executable, see <ulink url="http://www.php.net/manual/en/features.safe-mode.php#ini.safe-mode">safe mode settings</ulink>) and you are running off a <productname>Linux</productname> box, then you can use the output of <ulink url="http://linuxcommand.sourceforge.net/man_pages/ddate1.html">ddate</ulink> to construct a discordian date in mainfile.php:<indexterm><primary>mainfile.php</primary></indexterm></para><screen><![CDATA[$datetime = explode("Today is", exec('ddate'));
]]></screen><para>This will result in something like</para><screen><![CDATA[Setting Orange, the 41st day of Bureaucracy in the YOLD 3169
]]></screen><para>as the value of $datetime displayed in the News posts.<indexterm><primary>posts</primary></indexterm> More on this confusing topic in <ulink url="http://www.principiadiscordia.com/">Principia Discordia</ulink>, the Opiatum Magnum of the Discordian Philosophy,<indexterm><primary>Philosophy</primary></indexterm> as well as in the <ulink url="http://www.principiadiscordia.com/phpBB/index.php">Discordian Forum</ulink> - where Enlightenment meets Confusion (TM)...</para></sect2>
</sect1>
<sect1 id="deal-with-quotes-in-sitename"><title>How to deal with quotes in the site's name</title><para>What if O'Reilly decided to use <application>PHP-Nuke</application> for an "O'Reilly website"? He might find out the single quote in his name made it impossible to save the site's name in the Preferences of the administration panel (see <xref linkend="preferences">). <inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_frown.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_frown.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_frown.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_frown.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject> </para>
<para>Single quotes ('), double quotes (&quot;) and backslashes (\) need to be quoted in strings that will be entered in a database.<indexterm><primary>base</primary></indexterm> This is done by the <ulink url="http://www.php.net/manual/en/function.addslashes.php">PHP addslashes function</ulink>. Conversely, the <ulink url="http://www.php.net/manual/en/function.stripslashes.php">PHP stripslashes function</ulink> returns a string with backslashes stripped off (\' becomes ' and so on). To enable the use of single quotes in the site's name, do the following:</para><para>Add the line</para><screen><![CDATA[$sitename = stripslashes($sitename);
]]></screen><para>in mainfile.php,<indexterm><primary>mainfile.php</primary></indexterm> after the line that computes $sitename. According to your <application>PHP-Nuke</application> version, this line may be </para><screen><![CDATA[$sitename = $row[sitename];
]]></screen><para>(for version 6.8) or </para><screen><![CDATA[list($sitename, $nukeurl, $site_logo, $slogan, $startdate, $adminmail, $anonpost, $Default_Theme, $foot1, $foot2, $foot3, $commentlimit, $anonymous, $minpass,
]]><![CDATA[$pollcomm, $articlecomm, $broadcast_msg, $my_headlines, $top, $storyhome,
]]><![CDATA[$user_news, $oldnum, $ultramode, $banners, $backend_title, $backend_language,
]]><![CDATA[$language, $locale, $multilingual, $useflags, $notify, $notify_email,
]]><![CDATA[$notify_subject, $notify_message, $notify_from, $footermsgtxt, $email_send,
]]><![CDATA[$attachmentdir, $attachments, $attachments_view, $download_dir, $defaultpopserver,
]]><![CDATA[$singleaccount, $singleaccountname, $numaccounts, $imgpath, $filter_forward,
]]><![CDATA[$moderate, $admingraphic, $httpref, $httprefmax, $CensorMode, $CensorReplace,
]]><![CDATA[$copyright, $Version_Num) = sql_fetch_row($result, $dbi);
]]></screen><para>(for earlier 6.x versions). Repeat this for the file admin/modules/settings.<indexterm><primary>settings</primary></indexterm>php. While you are in this file, search for the line</para><screen><![CDATA[.""._SITENAME.":</td><td><input type='text' name='xsitename'
]]><![CDATA[value='$sitename' size='40' maxlength='255'>"
]]></screen><para>and change it to</para><screen><![CDATA[.""._SITENAME.":</td><td><input type=\"text\" name=\"xsitename\"
]]><![CDATA[value=\"$sitename\" size=\"40\" maxlength=\"255\">"
]]></screen><para>(we basically replace single quotes with escaped double ones in the above line, so that the single quote(s) in $sitename don't mess up the code). Finally , while still in admin/modules/settings.<indexterm><primary>settings</primary></indexterm>php, find the line</para><screen><![CDATA[global $prefix, $dbi;
]]></screen><para>in function ConfigSave and add the following line after it:</para><screen><![CDATA[$xsitename = addslashes($xsitename);
]]></screen></sect1>
<sect1 id="flash-php-nuke-news"><title>How to embed a Flash object in <application>PHP-Nuke</application> News</title><para>To embed a Flash object in a <application>PHP-Nuke</application> news article,<indexterm><primary>article</primary></indexterm> you have to use HTML code like the following - you must have administrator rights, or the whole code will be wiped out after submission.</para><screen><![CDATA[<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
]]><![CDATA[codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/
]]><![CDATA[swflash.cab#version=6,0,29,0" width="600" height="400">
]]><![CDATA[<param name="movie" value="yourmovie.swf">
]]><![CDATA[<param name=quality value=high>
]]><![CDATA[<embed src="http://www.yoursite.com/yourmovie.swf" quality=high
]]><![CDATA[pluginspage="http://www.macromedia.com/shockwave/download/index.cgi
]]><![CDATA[?P1_Prod_Version=ShockwaveFlash"
]]><![CDATA[type="application/x-shockwave-flash" width="600" height="400"></embed>
]]><![CDATA[</object>
]]></screen><para>Adapt the file name and dimensions to your situation.</para></sect1>
<sect1 id="backup-mysql-using-browser"><title>How to backup your MySQL database using only the browser</title><para>You want to do regular dumps of your MySQL database,<indexterm><primary>base</primary></indexterm> but you are lazy and would like to automate the task.</para><para>If your <acronym>PHP</acronym> installation permits execution of commands through system() (e.g. you are not running in safe mode, or, if you are, safe_mode_exec_dir contains all the commands you need), you can trigger a backup of your MySQL database,<indexterm><primary>base</primary></indexterm> just by pointing your browser to the following script (see <ulink url="http://www.karakas-online.de/forum/viewtopic.php?t=49">How to backup your MySQL database using only the browser</ulink>):</para><screen><![CDATA[<?php
]]><![CDATA[ // Enter your MySQL access data
]]><![CDATA[ $host= 'dbhost';
]]><![CDATA[ $user= 'dbuser';
]]><![CDATA[ $pass= 'dbpassword';
]]><![CDATA[ $db= 'db';
]]><![CDATA[ $backupdir = 'backups';
]]><![CDATA[ // Compute day, month, year, hour and min.
]]><![CDATA[ $today = getdate();
]]><![CDATA[ $day = $today[mday];
]]><![CDATA[ if ($day < 10) {
]]><![CDATA[ $day = "0$day";
]]><![CDATA[ }
]]><![CDATA[ $month = $today[mon];
]]><![CDATA[ if ($month < 10) {
]]><![CDATA[ $month = "0$month";
]]><![CDATA[ }
]]><![CDATA[ $year = $today[year];
]]><![CDATA[ $hour = $today[hours];
]]><![CDATA[ $min = $today[minutes];
]]><![CDATA[ $sec = "00";
]]><![CDATA[ // Execute mysqldump command.
]]><![CDATA[ // It will produce a file named $db-$year$month$day-$hour$min.gz
]]><![CDATA[ // under $DOCUMENT_ROOT/$backupdir
]]><![CDATA[ system(sprintf(
]]><![CDATA[ 'mysqldump --opt -h %s -u %s -p%s %s | gzip > %s/%s/%s-%s%s%s-%s%s.gz',
]]><![CDATA[ $host,
]]><![CDATA[ $user,
]]><![CDATA[ $pass,
]]><![CDATA[ $db,
]]><![CDATA[ getenv('DOCUMENT_ROOT'),
]]><![CDATA[ $backupdir,
]]><![CDATA[ $db,
]]><![CDATA[ $year,
]]><![CDATA[ $month,
]]><![CDATA[ $day,
]]><![CDATA[ $hour,
]]><![CDATA[ $min
]]><![CDATA[ ));
]]><![CDATA[ echo '+DONE';
]]><![CDATA[?>
]]></screen><para>Upload it to your backup directory (see code) and just reload it with your browser each time you want to do a backup.<indexterm><primary>backup</primary></indexterm></para><tip>
<title>
Use cron on the client, if it is not available on the server
</title>
<para>
If you are not allowed cron access on the web server (to start mysqldump directly there), you can set up your own cron job (on your home system!) to periodically call the above script.
</para>
</tip>
<tip>
<title>
Poor man's cron
</title>
<para>
If you don't have cron, or a similar functionality on your system, you can still modify the above script to inform the browser to reget the file every xxx hours. A poor man's cron, so to say.
<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_wink.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_wink.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_wink.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_wink.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject>
</para>
</tip>
<caution>
<title>
Protect your backup directory!
</title>
<para>
Of course, the backup directory should at least be protected with a .htaccess file.
</para>
</caution>
<caution>
<title>
Beware of the <acronym>PHP</acronym> execution limit!
</title>
<para>
If your <acronym>PHP</acronym> has some timeout limit set (often 30 sec), you will not be able to dump really large databases (larger than, say, 2-5MB) through this method. It is the same limitation, as with the phpMyAdmin DB backup option. The only alternative you have in this case is telnet or ssh access, see <xref linkend="restore-large-backup">.
</para>
</caution>
<para>Note that phpMyAdmin (<xref linkend="phpmyadmin">) also offers an excellent backup capability through the browser, with many options, like compression, structure and data backups,<indexterm><primary>backups</primary></indexterm> various backup file formats etc. However, you cannot automate backup creation with phpMyAdmin.<indexterm><primary>Admin</primary></indexterm></para></sect1>
</chapter>
<chapter id="tools"><title>Programmer's tools </title><sect1 id="database-tables"><title>The database tables </title><para>Here are the tables that comprise the <application>PHP-Nuke</application> database and what they serve for (FIXME:<indexterm><primary>FIXME</primary></indexterm> these are still from a very old version! Update! Data model!):</para><variablelist><varlistentry><term>nuke_access:<indexterm><primary>nuke_access</primary></indexterm>
</term><listitem><para>Defines various users profiles.</para></listitem></varlistentry><varlistentry><term>nuke_authors:<indexterm><primary>nuke_authors</primary></indexterm>
</term><listitem><para>Defines the administrators and their access levels.</para></listitem></varlistentry><varlistentry><term>nuke_autonews:<indexterm><primary>news</primary></indexterm>
</term><listitem><para>Manages automatic news.</para></listitem></varlistentry><varlistentry><term>nuke_banlist:<indexterm><primary>nuke_banlist</primary></indexterm>
</term><listitem><para>Manages banned users (those excluded from viewing the site).</para></listitem></varlistentry><varlistentry><term>nuke_banner:
</term><listitem><para>Manages banner campaigns,<indexterm><primary>campaigns</primary></indexterm> impressions and clicks.</para></listitem></varlistentry><varlistentry><term>nuke_bannerclient:
</term><listitem><para>Manages the banner campaign clients.<indexterm><primary>clients</primary></indexterm></para></listitem></varlistentry><varlistentry><term>nuke_bbtopics:
</term><listitem><para>Manages the BBCode.<indexterm><primary>BBCode</primary></indexterm></para></listitem></varlistentry><varlistentry><term>nuke_blocks:<indexterm><primary>nuke_blocks</primary></indexterm>
</term><listitem><para>List of created blocks.</para></listitem></varlistentry><varlistentry><term>nuke_catagories:<indexterm><primary>nuke_catagories</primary></indexterm>
</term><listitem><para>List of the categories.</para></listitem></varlistentry><varlistentry><term>nuke_comments:<indexterm><primary>comments</primary></indexterm>
</term><listitem><para>Manages comments and answers.</para></listitem></varlistentry><varlistentry><term>nuke_config:<indexterm><primary>nuke_config</primary></indexterm>
</term><listitem><para>Manages some configurations like the possibility to mail in HTML etc.</para></listitem></varlistentry><varlistentry><term>nuke_counter:<indexterm><primary>counter</primary></indexterm>
</term><listitem><para>Manages statistics.</para></listitem></varlistentry><varlistentry><term>nuke_disallow:<indexterm><primary>nuke_disallow</primary></indexterm>
</term><listitem><para>Blocks a user.</para></listitem></varlistentry><varlistentry><term>nuke_downloads_categories:<indexterm><primary>nuke_downloads_categories</primary></indexterm>
</term><listitem><para>Manages categories and subcategories for the download area.</para></listitem></varlistentry><varlistentry><term>nuke_downloads_downloads:<indexterm><primary>ads</primary></indexterm>
</term><listitem><para>Manages the files present in the download area.</para></listitem></varlistentry><varlistentry><term>nuke_downloads_editorials:<indexterm><primary>nuke_downloads_editorials</primary></indexterm>
</term><listitem><para>Manages the comments on the files.</para></listitem></varlistentry><varlistentry><term>nuke_downloads_modrequest:<indexterm><primary>nuke_downloads_modrequest</primary></indexterm>
</term><listitem><para>Manages the reporting of broken links.</para></listitem></varlistentry><varlistentry><term>nuke_downloads_newdownload:<indexterm><primary>download</primary></indexterm>
</term><listitem><para>Manages the insertion of files from third parties.</para></listitem></varlistentry><varlistentry><term>nuke_downloads_moddata:<indexterm><primary>data</primary></indexterm>
</term><listitem><para>Manages voting on files.</para></listitem></varlistentry><varlistentry><term>nuke_encyclopedya:<indexterm><primary>nuke_encyclopedya</primary></indexterm>
</term><listitem><para>Lists the various encyclopedias.</para></listitem></varlistentry><varlistentry><term>nuke_encyclopedia_text:<indexterm><primary>nuke_encyclopedia_text</primary></indexterm>
</term><listitem><para>Lists encyclopedia entries.</para></listitem></varlistentry><varlistentry><term>nuke_ephem:<indexterm><primary>nuke_ephem</primary></indexterm>
</term><listitem><para>Manages recurrent events.</para></listitem></varlistentry><varlistentry><term>nuke_faqanswer:<indexterm><primary>nuke_faqanswer</primary></indexterm>
</term><listitem><para>Archives the FAQ answers.</para></listitem></varlistentry><varlistentry><term>nuke_faqcategories:<indexterm><primary>nuke_faqcategories</primary></indexterm>
</term><listitem><para>Manages the categories in which the FAQ are subdivided.</para></listitem></varlistentry><varlistentry><term>nuke_forum_access:<indexterm><primary>nuke_forum_access</primary></indexterm>
</term><listitem><para>Records the last access of the users.</para></listitem></varlistentry><varlistentry><term>nuke_forum_mods:<indexterm><primary>nuke_forum_mods</primary></indexterm>
</term><listitem><para>Defines moderators of the forums.</para></listitem></varlistentry><varlistentry><term>nuke_forums:<indexterm><primary>nuke_forums</primary></indexterm>
</term><listitem><para>Defines the active forums.</para></listitem></varlistentry><varlistentry><term>nuke_forumtopics:<indexterm><primary>nuke_forumtopics</primary></indexterm>
</term><listitem><para>Defines forum topics.</para></listitem></varlistentry><varlistentry><term>nuke_headlines:<indexterm><primary>headlines</primary></indexterm>
</term><listitem><para>Defines the sources from which to take news with the blocks.</para></listitem></varlistentry><varlistentry><term>nuke_links_categories:<indexterm><primary>nuke_links_categories</primary></indexterm>
</term><listitem><para>Defines the categories in which the links are subdivided. </para></listitem></varlistentry><varlistentry><term>nuke_links_editorials:<indexterm><primary>nuke_links_editorials</primary></indexterm>
</term><listitem><para>Manages the judgments on the links.</para></listitem></varlistentry><varlistentry><term>nuke_links_links:<indexterm><primary>nuke_links_links</primary></indexterm>
</term><listitem><para>Archives the links.</para></listitem></varlistentry><varlistentry><term>nuke_links_modrequest:<indexterm><primary>nuke_links_modrequest</primary></indexterm>
</term><listitem><para>Archives the messages related to the link (broken link etc.).</para></listitem></varlistentry><varlistentry><term>nuke_links_newlink:<indexterm><primary>nuke_links_newlink</primary></indexterm>
</term><listitem><para>Archives links suggested for insertion.</para></listitem></varlistentry><varlistentry><term>nuke_links_votedata:<indexterm><primary>data</primary></indexterm>
</term><listitem><para>Archives link votes.</para></listitem></varlistentry><varlistentry><term>nuke_main:<indexterm><primary>nuke_main</primary></indexterm>
</term><listitem><para>Defines which is the main module that must be included in index.php.</para></listitem></varlistentry><varlistentry><term>nuke_message:<indexterm><primary>nuke_message</primary></indexterm>
</term><listitem><para>Manages the home page messages.</para></listitem></varlistentry><varlistentry><term>nuke_modules:<indexterm><primary>modules</primary></indexterm>
</term><listitem><para>Lists and manages the installed modules.</para></listitem></varlistentry><varlistentry><term>nuke_pages:<indexterm><primary>nuke_pages</primary></indexterm></term>
<listitem><para>&nbsp;</para></listitem></varlistentry><varlistentry><term>nuke_pages_categories:<indexterm><primary>nuke_pages_categories</primary></indexterm></term>
<listitem><para>&nbsp;</para></listitem></varlistentry><varlistentry><term>nuke_poll_check:<indexterm><primary>nuke_poll_check</primary></indexterm>
</term><listitem><para>List of the IP addresses that have voted in last 24 hours.</para></listitem></varlistentry><varlistentry><term>nuke_poll_data:<indexterm><primary>nuke_poll_data</primary></indexterm>
</term><listitem><para>List of survey answers.</para></listitem></varlistentry><varlistentry><term>nuke_poll_desc:<indexterm><primary>nuke_poll_desc</primary></indexterm>
</term><listitem><para>List of present and past surveys.</para></listitem></varlistentry><varlistentry><term>nuke_pollcomments:
</term><listitem><para>Comment to the survey.<indexterm><primary>survey</primary></indexterm></para></listitem></varlistentry><varlistentry><term>nuke_posts:<indexterm><primary>nuke_posts</primary></indexterm>
</term><listitem><para>Main titles of forum posts</para></listitem></varlistentry><varlistentry><term>nuke_posts_text:<indexterm><primary>nuke_posts_text</primary></indexterm></term>
<listitem><para>&nbsp;</para></listitem></varlistentry><varlistentry><term>nuke_priv_msgs:<indexterm><primary>nuke_priv_msgs</primary></indexterm>
</term><listitem><para>Manages the module private messages.</para></listitem></varlistentry><varlistentry><term>nuke_queue:<indexterm><primary>nuke_queue</primary></indexterm>
</term><listitem><para>Lists the texts waiting for publication</para></listitem></varlistentry><varlistentry><term>nuke_quotes:<indexterm><primary>nuke_quotes</primary></indexterm></term>
<listitem><para>&nbsp;</para></listitem></varlistentry><varlistentry><term>nuke_ranks:<indexterm><primary>nuke_ranks</primary></indexterm>
</term><listitem><para>Registers the votes for the news</para></listitem></varlistentry><varlistentry><term>nuke_referer:<indexterm><primary>nuke_referer</primary></indexterm>
</term><listitem><para>Lists where the last x rows come from</para></listitem></varlistentry><varlistentry><term>nuke_related:<indexterm><primary>nuke_related</primary></indexterm>
</term><listitem><para>Associates eventual links to the topics.</para></listitem></varlistentry><varlistentry><term>nuke_reviews:<indexterm><primary>reviews</primary></indexterm></term>
<listitem><para>&nbsp;</para></listitem></varlistentry><varlistentry><term>nuke_reviews_add<indexterm><primary>nuke_reviews_add</primary></indexterm></term>
<listitem><para>&nbsp;</para></listitem></varlistentry><varlistentry><term>nuke_reviews_comments:
</term><listitem><para>Comments to the reviews.<indexterm><primary>reviews</primary></indexterm></para></listitem></varlistentry><varlistentry><term>nuke_reviews_main:
</term><listitem><para>main table of the reviews.<indexterm><primary>reviews</primary></indexterm></para></listitem></varlistentry><varlistentry><term>nuke_seccont:<indexterm><primary>nuke_seccont</primary></indexterm>
</term><listitem><para>Lists the section texts.</para></listitem></varlistentry><varlistentry><term>nuke_sections:<indexterm><primary>nuke_sections</primary></indexterm>
</term><listitem><para>Lists the active sections.</para></listitem></varlistentry><varlistentry><term>nuke_session:<indexterm><primary>nuke_session</primary></indexterm>
</term><listitem><para>Lists the active sessions.</para></listitem></varlistentry><varlistentry><term>nuke_smiles:
</term><listitem><para>Lists the supported emoticons.<indexterm><primary>icons</primary></indexterm></para></listitem></varlistentry><varlistentry><term>nuke_stats_date:<indexterm><primary>date</primary></indexterm>
</term><listitem><para>Statistics module.</para></listitem></varlistentry><varlistentry><term>nuke_stats_hour:<indexterm><primary>nuke_stats_hour</primary></indexterm>
</term><listitem><para>Statistics module...</para></listitem></varlistentry><varlistentry><term>nuke_stats_month:<indexterm><primary>nuke_stats_month</primary></indexterm>
</term><listitem><para>Statistics module.</para></listitem></varlistentry><varlistentry><term>nuke_stats_year:<indexterm><primary>nuke_stats_year</primary></indexterm>
</term><listitem><para>Statistics module.</para></listitem></varlistentry><varlistentry><term>nuke_stories:<indexterm><primary>nuke_stories</primary></indexterm>
</term><listitem><para>Texts of the news.</para></listitem></varlistentry><varlistentry><term>nuke_stories_cat:<indexterm><primary>nuke_stories_cat</primary></indexterm>
</term><listitem><para>Categories of the news.</para></listitem></varlistentry><varlistentry><term>nuke_topics:<indexterm><primary>nuke_topics</primary></indexterm>
</term><listitem><para>List of topics.</para></listitem></varlistentry><varlistentry><term>nuke_users:<indexterm><primary>nuke_users</primary></indexterm>
</term><listitem><para>List of users.</para></listitem></varlistentry><varlistentry><term>nuke_words:<indexterm><primary>nuke_words</primary></indexterm>
</term><listitem><para>Words to censure.</para></listitem></varlistentry></variablelist></sect1>
<sect1 id="HTML-syntax"><title>The syntax of HTML code</title><para>HTML is the language that is used to construct web pages. It is somewhat obsolete, as it is going to be replaced by XHTML.<indexterm><primary>XHTML</primary></indexterm> In this section we will have a look at the HTML code we need in order to </para><itemizedlist><listitem><para>format text,</para></listitem><listitem><para>create links, </para></listitem><listitem><para>insert images,<indexterm><primary>images</primary></indexterm></para></listitem><listitem><para>create tables.<indexterm><primary>tables</primary></indexterm></para></listitem></itemizedlist><sect2 id="HTML-format-text"><title>How to format text in HTML</title><para>To format a text in bold, you can use the &lt;b&gt; tag (deprecated in XHTML,<indexterm><primary>XHTML</primary></indexterm> use CSS instead, see <xref linkend="change-font-size-php-nuke">, <xref linkend="CSS-syntax">!). We recall that in HTML in most cases you have to open and close the tag. Thus, the code</para><screen><![CDATA[<b>Hello</b> World
]]></screen><para>means that the word &ldquo;Hello&rdquo; shall be in bold face, while the rest of the sentence will be in normal face, since the &lt;b&gt; tag was closed with &lt;/b&gt; immediately after the word &ldquo;Hello&rdquo;. Other formatting tags are:</para><itemizedlist><listitem><para>&lt;u&gt;&lt;/u&gt; (for underlining a phrase)</para></listitem><listitem><para>&lt;i&gt;&lt;/i&gt; (for italicizing,<indexterm><primary>italicizing</primary></indexterm> i.e. render a phrase with cursive face)</para></listitem></itemizedlist><para>But how can we change not only the face, but also the colour,<indexterm><primary>colour</primary></indexterm> the size and the font? For this, the &lt;font&gt; tag comes to our help (also deprecated<indexterm><primary>deprecated</primary></indexterm> in XHTML,<indexterm><primary>XHTML</primary></indexterm> use CSS instead, see <xref linkend="change-font-size-php-nuke">, <xref linkend="CSS-syntax">!). Let's take a concrete example and analyze it:</para><screen><![CDATA[<font color="#FF0000" size="2">Hello World</font>
]]></screen><para>The code assigns some values to attributes of the font tag, that will apply to the &ldquo;Hello World&rdquo; text:</para><itemizedlist><listitem><para>color=&quot;#FF0000&quot;: assigns the red colour to the text. Why red? Because only the first two hex numbers are set (to FF, which is the hexadecimal notation for 255), meaning that only the red component is active (there are three components, red, grren and blue, each one taking up two hex digits in the colur notation).</para><tip>
<title>
Colour wheels
</title>
<para>
A useful tool in exploring the visible spectrum in HTML is the <ulink url="http://www.karakas-online.de/myServices/colorwheel.html">colour wheel</ulink>. Just hover over the wheel with your mouse to view 4096 colors in their web safe, web smart and unsafe versions.<inlinemediaobject> <![ %output.print.png; [ <imageobject> <imagedata fileref="./images/icon_cool.png" format="PNG"> </imageobject> ]]> <![ %output.print.pdf; [ <imageobject> <imagedata fileref="icon_cool.pdf" format="PDF" scale="65"> </imageobject> ]]> <![ %output.print.eps; [ <imageobject> <imagedata fileref="./images/icon_cool.eps" format="EPS"> </imageobject> ]]> <![ %output.print.bmp; [ <imageobject> <imagedata fileref="icon_cool.bmp" format="BMP"> </imageobject> ]]> <textobject> <phrase>Inline graphic</phrase> </textobject> </inlinemediaobject>
</para>
<para>
You can also use the <ulink url="http://www.karakas-online.de/popups/">colour popups of the Tag-o-matic</ulink> to show all 216 web-safe colours in a virtual colour card.
</para>
</tip>
</listitem><listitem><para>size = 2: assigns the size 2 to the characters of the &ldquo;Hello World&rdquo; string.</para></listitem></itemizedlist></sect2>
<sect2 id="HTML-create-link"><title>How to create a link in HTML</title><para>We recall that a link in HTML is always composed of two parts, the clickable part (the link text) and the URL (Uniform Resource Locator,<indexterm><primary>Locator</primary></indexterm> the destination site, page or resource). Here is an example:</para><itemizedlist><listitem><para>Clickable part (link text): <application>PHP-Nuke</application> HOWTO.<indexterm><primary>HOWTO</primary></indexterm></para></listitem><listitem><para>URL:<indexterm><primary>URL</primary></indexterm> http://www.karakas-online.de/EN-Book/</para></listitem></itemizedlist><para>The HTML code for this link is:</para><screen><![CDATA[<a href=]]>&rdquo;<![CDATA[http://www.karakas-online.de/EN-Book/]]>&rdquo;<![CDATA[>PHP-Nuke HOWTO</a>
]]></screen><para>which will look like: <ulink url="http://www.karakas-online.de/EN-Book/">PHP-Nuke HOWTO</ulink>. As you can see, the &lt;a&gt; tag is closed with &lt;/a&gt;.</para><para>Some rules for creating links:</para><itemizedlist><listitem><para>If the link points to an external site, the address must always start with &ldquo;http://&rdquo;.</para></listitem><listitem><para>If the link points to an internal page in the same directory as the page setting the link, it suffices to give only the name of the file. This will be a little faster, as we save a DNS query on the site's fully quallified domain name. It also saves you administration headaches,<indexterm><primary>headaches</primary></indexterm> should you choose to move your files under a different directory: in case of absolute paths, you would have to change all of them in your code. Finally, if you use relative paths, you can still navigate around your pages locally, on your development server,<indexterm><primary>server</primary></indexterm> without having to upload all files on the web server first. See also <ulink url="http://www.compugoddess.com/relvsabs.htm">Relative vs. Absolute Links</ulink> and <ulink url="http://www.webdiner.com/webadv/begin/paths.htm">About Paths</ulink>.</para></listitem><listitem><para>We can pass parameters (the so-called &ldquo;URL parameters&rdquo;) on the link. <application>PHP-Nuke</application> make heavy use of this feature: all <application>PHP-Nuke</application> modules are called through a link that passes the module's name to the modules.<indexterm><primary>modules</primary></indexterm>php script, as in the following example for the News module:<indexterm><primary>module</primary></indexterm></para><screen><![CDATA[http://www.yousite.com/modules.php?name=News
]]></screen></listitem><listitem><para>The link text can be treated just as any other text in HTML,<indexterm><primary>HTML</primary></indexterm> assigning it colour and size, in the same way as we do it for normal text (see <xref linkend="HTML-format-text">).</para></listitem></itemizedlist></sect2>
<sect2 id="HTML-insert-image"><title>How to insert an image in HTML</title><para>To insert an image in an HTML file (or <application>PHP-Nuke</application> news article (see <xref linkend="preinstalled-modules">), or <application>PHP-Nuke</application> theme (see <xref linkend="topic-structure">)), we use the &lt;img&gt; tag. For example, to insert an image called photo.png,<indexterm><primary>png</primary></indexterm> located in the same directory as the file that is going to show it, we write:</para><screen><![CDATA[<img src="photo.png" alt=]]>&rdquo;<![CDATA[description of the photo]]>&rdquo;<![CDATA[></img>
]]></screen><para>The alt tag serves as an alternative, textual description of the image. This description is shown when we hover with the mouse over the image, but it is also used by speech browsers like <ulink url="http://www.freedomscientific.com/fs_products/software_jaws.asp">JAWS</ulink>, or text-only browsers like <ulink url="http://lynx.isc.org">Lynx</ulink>, instead of the image file, to convey an idea of the image object to people with disabilities,<indexterm><primary>disabilities</primary></indexterm> see day 23 of the 30-day <ulink url="http://diveintoaccessibility.org">Dive Into Accessibility</ulink> tutorial on <ulink url="http://diveintoaccessibility.org/day_23_providing_text_equivalents_for_images.html">Providing text equivalents for images</ulink>.</para><para>In case your image is included in a different folder, say images/, as is often the case with PHP-Nuke, the code looks like:</para><screen><![CDATA[<img src="images/photo.png" alt=]]>&rdquo;<![CDATA[description of the photo]]>&rdquo;<![CDATA[></img>
]]></screen><para>Note that we only need to specify a relative path to the image file, relative to the <application>PHP-Nuke</application> root directory, that is. The reason for this is that in <application>PHP-Nuke</application> all articles, stories etc. are shown through the modules.<indexterm><primary>modules</primary></indexterm>php file (which is passed the right module name through an URL parameter,<indexterm><primary>parameter</primary></indexterm> as shown in <xref linkend="HTML-create-link">), which is located in the <application>PHP-Nuke</application> root directory (by the way, this is the same directory where the config.<indexterm><primary>config</primary></indexterm>php file (<xref linkend="config-php-file">) is also located).</para><para>Also note that, to remain compatible with the HTML standards,<indexterm><primary>standards</primary></indexterm> you have to include the values of the attributes, like src or alt, in double quotes,<indexterm><primary>quotes</primary></indexterm> as in the examples above. You can check your site for HTML standards compliance with the <ulink url="http://www.karakas-online.de/myServices/w3c-html-validator.html">W3C HTML validator</ulink>.</para><para>You can also make the image clickable, combining the two techniques of creating a link (see <xref linkend="HTML-create-link">) and inserting an image:</para><screen><![CDATA[<a href=]]>&rdquo;<![CDATA[http://www.karakas-online.de/EN-Book/]]>&rdquo;<![CDATA[>
]]><![CDATA[<img src=]]>&rdquo;<![CDATA[ http://www.karakas-online.de/EN-Book/images/nuke.png]]>&rdquo;<![CDATA[
]]><![CDATA[alt=]]>&rdquo;<![CDATA[PHP-Nuke HOWTO]]>&rdquo;<![CDATA[></img></a>
]]></screen></sect2>
<sect2 id="HTML-create-table"><title>How to create a table in HTML</title><para>The important HTML tags for tables are:</para><itemizedlist><listitem><para>&lt;table&gt;&lt;/table&gt; (opens and closes a table)</para></listitem><listitem><para>&lt;tr&gt;&lt;/tr&gt; (opens and closes a table row)</para></listitem><listitem><para>&lt;td&gt;&lt;td&gt; (opens and closes a table cell, inside a column)</para></listitem></itemizedlist><para>A table with one row and one column will be constructed with the code:</para><screen><![CDATA[<table width="100%" border="0">
]]><![CDATA[ <tr>
]]><![CDATA[ <td></td>
]]><![CDATA[ </tr>
]]><![CDATA[</table>
]]></screen><para>Here you can also see how to use some attributes,<indexterm><primary>attributes</primary></indexterm> like &quot;width&quot;, which can attain values in pixels or percent, and &quot;border&quot;<indexterm><primary>border</primary></indexterm>, which, if set to &quot;0&quot; as in the above example, will suppress the drawing of borders around table cells, thus making the structure of the table invisible to the reader.</para><para>A table with two rows and two columns can be created with the code:</para><screen><![CDATA[<table width="500" border="0">
]]><![CDATA[ <tr>
]]><![CDATA[ <td width="200"></td>
]]><![CDATA[ <td></td>
]]><![CDATA[ </tr>
]]><![CDATA[ <tr>
]]><![CDATA[ <td width="200"></td>
]]><![CDATA[ <td></td>
]]><![CDATA[ </tr>
]]><![CDATA[</table>
]]></screen><para>As you can see in this example, the table has the following properties:</para><itemizedlist><listitem><para>two rows,</para></listitem><listitem><para>two columns,</para></listitem><listitem><para>fixed total table width of 500 pixels,<indexterm><primary>pixels</primary></indexterm></para></listitem><listitem><para>fixed width of the left column: 200 pixels.<indexterm><primary>pixels</primary></indexterm></para></listitem></itemizedlist><para>Content is inserted in the columns, while the rows have a higher priority and are inserted first. For example, if we wanted to insert the text &ldquo;PHP-Nuke&rdquo; in the first line of the left column of the above table, the code would look like this:</para><screen><![CDATA[<table width="500" border="0">
]]><![CDATA[ <tr>
]]><![CDATA[ <td width="200">PHP-Nuke</td>
]]><![CDATA[ <td></td>
]]><![CDATA[ </tr>
]]><![CDATA[ <tr>
]]><![CDATA[ <td width="200"></td>
]]><![CDATA[ <td></td>
]]><![CDATA[ </tr>
]]><![CDATA[</table>
]]></screen><note>
<title>
HTML layout: tables was yesterday, today is CSS!
</title>
<para>
Tables are meant to hold tabular data. They should not be used for layout purposes, even though they are being widely misused for this purpose, also in <application>PHP-Nuke</application>. The correct way to position your data today, is not through tables, but through CSS (see <xref linkend="CSS-syntax"> and <ulink url="http://www.sitepoint.com/books/css1/">Designing Without Tables</ulink>). If you decide to use tables, you should be <ulink url="http://diveintoaccessibility.org/day_19_using_real_table_headers.html">using real table headers</ulink> and <ulink url="http://diveintoaccessibility.org/day_20_providing_a_summary_for_tables.html">providing a table summary</ulink>, for accessibility reasons.
</para>
</note>
</sect2>
</sect1>
<sect1 id="CSS-syntax"><title>The syntax of CSS</title><para>Cascading Style Sheets (CSS) are files that contain presentational information.<indexterm><primary>information</primary></indexterm> They are associated wit an HTML or XHTML file and help us separate presentation<indexterm><primary>presentation</primary></indexterm> from content, thus rendering the management of our pages much easier and our code much cleaner.</para><para>CSS files work as follows: they contain a series of rules,<indexterm><primary>rules</primary></indexterm> to every rule is appended a group of formatting instructions. The formatting instructions are only applied by the client's browser to those parts of the HTML page specified by the preceding rule. With a CSS we can do everything that we could do with the deprecated HTML<indexterm><primary>HTML</primary></indexterm> tags, like setting the font, the font size or colour (&lt;font&gt; tag), the font face (bold with the &lt;b&gt; tag or italics with the &lt;i&gt; tag), link colour<indexterm><primary>colour</primary></indexterm> and much more that was not previously possible.</para><para>In the following we will examine some examples. In PHP-Nuke, the CSS file is contained in a file called style.css,<indexterm><primary>style.css</primary></indexterm> located in the style folder of the corresponding theme.<indexterm><primary>theme</primary></indexterm> For the NukeNews theme,<indexterm><primary>theme</primary></indexterm> for example, the CSS file is themes/NukeNews/style/style.css.</para><para>For the HTML &lt;body&gt; tag, we can set up its attributes in the CSS as follows:</para><screen><![CDATA[body {background: #FFF; color:#003366; margin-left: 0; margin-top: 0;}
]]></screen><para>This rule specifies a few attributes that will be valid through the whole HTML body (unless overriden by a more specific rule):</para><itemizedlist><listitem><para>background:<indexterm><primary>background</primary></indexterm> assigns a background colour to the page.</para></listitem><listitem><para>color: defines the text colour.<indexterm><primary>colour</primary></indexterm></para></listitem><listitem><para>margin-left and margin-top:<indexterm><primary>margin-top</primary></indexterm> define the space between the margin of the page and the margin of the content.</para></listitem></itemizedlist><para>The concepts of margin, border and padding follow a page model that is described in W3C's working draft <ulink url="http://www.w3.org/TR/2003/WD-css3-page-20031218/">CSS3 Paged Media Module</ulink>, version of Dec. 18th 2003. <xref linkend="fig-page-area-model">, taken from this document (Copyright &copy;<indexterm><primary>copy</primary></indexterm> 2003 <ulink url="http://www.w3.org">W3C</ulink> (<ulink url="http://www.lcs.mit.edu">MIT</ulink>, <ulink url="http://www.ercim.org">ERCIM</ulink>, <ulink url="http://www.keio.ac.jp">Keio</ulink>), All Rights Reserved) illustrates the various geometric notions of this page model.<indexterm><primary>model</primary></indexterm> Note that the <ulink url="http://www.w3.org/TR/2003/WD-xsl11-20031217/#area_model">XSL area model</ulink> is deliberately very similar to the CSS one.</para><para>
<figure id="fig-page-area-model">
<title>
CSS page area model.
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1204;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1204;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1204;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1204;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>CSS page area model.</phrase>
</textobject>
<caption>
<para>CSS page area model.</para>
</caption>
</mediaobject>
</figure>
</para><para>CSS allows for the creation of whole sets of rules that will be applied to the parts of the page those rules specify. Such a rule could for example look like:</para><screen><![CDATA[.headercoldx {
]]><![CDATA[ vertical-align: top;
]]><![CDATA[ width:500px;
]]><![CDATA[ background-image: url(http://yoursite.com/themes/sometheme/images/bgheader.png);
]]><![CDATA[ background-color:#ffffff;
]]><![CDATA[ font: 11px arial, verdana, helvetica;
]]><![CDATA[ color: #000
]]><![CDATA[}
]]></screen><para>The .headercoldx part is a so-called <ulink url="http://www.w3.org/TR/REC-CSS2/selector.html">CSS Selector</ulink>, specifically a class selector.<indexterm><primary>selector</primary></indexterm> It selects (applies to) HTML elements of the class &ldquo;headercoldx&rdquo;. If we had an element name in front of the dot, the selector would apply only to that element and only if it were of the headercoldx class.<indexterm><primary>class</primary></indexterm> Since in the above example there is no element name in front of the dot, the formatting instructions that follow are applied to <emphasis>all</emphasis> HTML elements of the headercoldx class (see also <ulink url="http://www.w3.org/TR/REC-CSS2/selector.html#class-html">Class selectors</ulink>). Thus, all HTML elements that are of class headercoldx will </para><itemizedlist><listitem><para>be vertically aligned to the top of the box that contains them,</para></listitem><listitem><para>have a width of 500 pixels,<indexterm><primary>pixels</primary></indexterm></para></listitem><listitem><para>display bgheader.<indexterm><primary>header</primary></indexterm>png as background image,</para></listitem><listitem><para>use white as the background colour,<indexterm><primary>colour</primary></indexterm></para></listitem><listitem><para>use a 11 pixel font, preferably arial, or, if arial is not available, verdana,<indexterm><primary>verdana</primary></indexterm> or, if verdana is also missing, helvetica,</para></listitem><listitem><para>use black for the text colour.<indexterm><primary>colour</primary></indexterm></para></listitem></itemizedlist><para>What remains to be seen, is how to mark HTML elements as being members of a certain class,<indexterm><primary>class</primary></indexterm> like headercoldx above. This is easily done through the use of the class attribute,<indexterm><primary>attribute</primary></indexterm> as the following example demonstrates for the table we constructed in <xref linkend="HTML-create-table">:</para><screen><![CDATA[<table class="headercoldx">
]]><![CDATA[ <tr>
]]><![CDATA[ <td width="200">PHP-Nuke</td>
]]><![CDATA[ <td></td>
]]><![CDATA[ </tr>
]]><![CDATA[ <tr>
]]><![CDATA[ <td width="200"></td>
]]><![CDATA[ <td></td>
]]><![CDATA[ </tr>
]]><![CDATA[</table>
]]></screen><para>As you can see, all attributes of the table tag have been removed and replaced by the class attribute.<indexterm><primary>attribute</primary></indexterm> The formatting information that was contained in the replaced attributes<indexterm><primary>attributes</primary></indexterm> is now contained in the group of formatting instructions that follows the class selector for the headercoldx class.<indexterm><primary>class</primary></indexterm></para><para>In the following example, a different selector is used, one that selects the <ulink url="http://www.w3.org/TR/REC-CSS2/selector.html#link-pseudo-classes">pseudo-class :link</ulink> and one that selects the <ulink url="http://www.w3.org/TR/REC-CSS2/selector.html#dynamic-pseudo-classes">dynamic pseudo-class :hover</ulink>:</para><screen><![CDATA[A:link {BACKGROUND: none; COLOR: #003366; FONT-SIZE: 11px; FONTFAMILY:
]]><![CDATA[Verdana, Helvetica; TEXT-DECORATION: underline}
]]><![CDATA[
]]><![CDATA[A:hover {color:003366; background-color:#FFCC33; FONT-SIZE: 11px; FONTFAMILY:
]]><![CDATA[Verdana, Helvetica; TEXT-DECORATION: underline }
]]></screen><para>The first rule specifies the formatting of a link, the second overrides the first one for the case that the user hovers with the mouse over the link.</para><para>Conflicting rules are intrinsic to the CSS mechanism. To find the value for an element/property combination, the following algorithm must be followed (see <ulink url="http://www.ezdefinition.com/eng/catalog/pages/comp/870/870.html">The cascade</ulink>):</para><orderedlist><listitem><para>Find all declarations that apply to the element/property in question. Declarations apply if the selector matches the element in question. If no declarations apply, the inherited value is used. If there is no inherited value (this is the case for the 'HTML' element and for properties that do not inherit), the initial value is used. </para></listitem><listitem><para>Sort the declarations by explicit weight: declarations marked '!important' carry more weight than unmarked (normal) declarations.<indexterm><primary>ations</primary></indexterm></para></listitem><listitem><para>Sort by origin:<indexterm><primary>origin</primary></indexterm> the author's style sheets override the reader's style sheet which override the UA's default values. An imported style sheet has the same origin as the style sheet from which it is imported.</para></listitem><listitem><para>Sort by specificity of selector:<indexterm><primary>selector</primary></indexterm> more specific selectors will override more general ones. To find the specificity, count the number of <acronym>ID</acronym> attributes in the selector<indexterm><primary>selector</primary></indexterm> (a), the number of CLASS attributes in the selector (b), and the number of tag names in the selector (c). Concatenating the three numbers (in a number system with a large base) gives the specificity. Some examples:</para><itemizedlist><listitem><para>LI {...} /* a=0 b=0 c=1 -&gt; specificity = 1 */</para></listitem><listitem><para>UL LI {...} /* a=0 b=0 c=2 -&gt; specificity = 2 */</para></listitem><listitem><para>UL OL LI {...} /* a=0 b=0 c=3 -&gt; specificity = 3 */</para></listitem><listitem><para>LI.red {...} /* a=0 b=1 c=1 -&gt; specificity = 11 */ </para></listitem><listitem><para>UL OL LI.red {...} /* a=0 b=1 c=3 -&gt; specificity = 13 */ </para></listitem><listitem><para>#x34y {...} /* a=1 b=0 c=0 -&gt; specificity = 100 */ </para></listitem></itemizedlist><para>Pseudo-elements and pseudo-classes are counted as normal elements and classes, respectively.</para></listitem><listitem><para>Sort by order specified: if two rules have the same weight, the latter specified wins. Rules in imported style sheets are considered to be before any rules in the style sheet itself. </para></listitem></orderedlist><tip>
<title>
CSS of this HOWTO
</title>
<para>
This HOWTO uses a <ulink url="ck-style.css">special CSS file</ulink> (well, at least in its original version that you can always find in <ulink url="http://www.karakas-online.de/EN-Book/">PHP-Nuke HOWTO</ulink>), tailored to the classes created by the DocBook stylesheets, which are used for its creation (see <xref linkend="book-behind-book">). If you like the formatting, you can read more about it in <ulink url="http://www.karakas-online.de/myLinuxTips/css-for-docbook.html">CSS file for DocBook</ulink>.
</para>
</tip>
</sect1>
<sect1 id="PHP-syntax"><title>The syntax of <acronym>PHP</acronym> code</title><para>PHP-Nuke is written in <ulink url="http://www.php.net">PHP</ulink> and uses the <ulink url="http://www.mysql.com">MySQL</ulink> database.<indexterm><primary>base</primary></indexterm> In this section we will present some examples of <acronym>PHP</acronym> code. We don't try to teach you a new programming language, but only to illustrate how some things work.</para><sect2 id="PHP-variables"><title>Variables</title><para>Variables are those elements that are given variable values, depending on the case.<indexterm><primary>case</primary></indexterm> Here is an example:</para><screen>
<![CDATA[<?]]> <co id="PHP-variables-1">
<![CDATA[if ($foobar == 1)){]]> <co id="PHP-variables-2">
<![CDATA[ echo "The value is 1";]]> <co id="PHP-variables-3">
<![CDATA[} else {]]>
<![CDATA[ echo "The value is not 1";]]> <co id="PHP-variables-4">
<![CDATA[}]]>
<![CDATA[?>]]> <co id="PHP-variables-5">
</screen>
<calloutlist>
<callout arearefs="PHP-variables-1">
<para>
As with every <acronym>PHP</acronym> script, we have to designate its start and end. Here is the start...
</para>
</callout>
<callout arearefs="PHP-variables-2">
<para>
We check if the foobar variable has the value 1.
</para>
</callout>
<callout arearefs="PHP-variables-3">
<para>
If it does, we output a message. We do this with the echo function. This functions will print whatever is included in the double quotes. The double quotes may contain other variables (in which case the echo command will print their values), HTML code etc. If you want to print double quotes, you have to escape them with a backslash.
</para>
</callout>
<callout arearefs="PHP-variables-4">
<para>
If it doesn't, we also output an aproppriate message.
</para>
</callout>
<callout arearefs="PHP-variables-5">
<para>
...and here is the end of the script.
</para>
</callout>
</calloutlist>
<para>See also <ulink url="http://www.php.net/language.variables">PHP variables</ulink>.</para></sect2>
<sect2 id="PHP-functions"><title>Functions</title><para>Here is an example of a simple <acronym>PHP</acronym> function:<indexterm><primary>function</primary></indexterm></para><screen><![CDATA[function get_lang($module) {
]]><![CDATA[
]]><![CDATA[ global $currentlang, $language;
]]><![CDATA[
]]><![CDATA[ HERE GOES THE FUNCTION CODE
]]><![CDATA[
]]><![CDATA[}
]]></screen><para>It has the following structure,<indexterm><primary>structure</primary></indexterm> common to every <acronym>PHP</acronym> function:</para><itemizedlist><listitem><para>the function name, preceded by the keyword &quot;function&quot;<indexterm><primary>function</primary></indexterm>,</para></listitem><listitem><para>the function parameters in the parenthesis,<indexterm><primary>parenthesis</primary></indexterm></para></listitem><listitem><para>the global variables that we intend to use in this function, registered<indexterm><primary>registered</primary></indexterm> through the &quot;global&quot;<indexterm><primary>global</primary></indexterm> keyword (we cannot use any global variables, if we do not register them as such),</para></listitem><listitem><para>the curly brackets that include the function's content</para></listitem></itemizedlist><para>Functions may be called from anywhere in the <acronym>PHP</acronym> code. See also <ulink url="http://www.php.net/manual/en/functions.php">PHP functions</ulink>.</para></sect2>
<sect2 id="PHP-switches"><title>Switches</title><para>A switch in <acronym>PHP</acronym> allows us to take certain actions depending on the value of a certain variable, as in the following example, where we check the value of the $pa variable:</para><screen><![CDATA[switch($pa) {
]]><![CDATA[ case "showpage":
]]><![CDATA[ showpage($pid, $page);
]]><![CDATA[ break;
]]><![CDATA[ case "list_pages_categories":
]]><![CDATA[ list_pages_categories($cid);
]]><![CDATA[ break;
]]><![CDATA[ default:
]]><![CDATA[ list_pages();
]]><![CDATA[ break;
]]><![CDATA[}
]]></screen><para>In case $pa has the value &ldquo;showpage<indexterm><primary>showpage</primary></indexterm>&rdquo;, we call the showpage() function,<indexterm><primary>function</primary></indexterm> in case it has the value &quot;list_pages_categories&quot;, we call the list_pages_categories() function.<indexterm><primary>function</primary></indexterm> If $pa does not have any of these two values, or any value at all, we enter the default case and call list_pages(). See also <ulink url="http://www.php.net/manual/en/control-structures.php">PHP control structures</ulink>.</para><para>Switch statements are often used in module development (especially in the module administration functions, see <xref linkend="module-admin">). So, if you declared in a module admin case file a switch like: </para><screen><![CDATA[switch($func) {
]]><![CDATA[ case "func-one":
]]><![CDATA[ funct-one();
]]><![CDATA[ break;
]]><![CDATA[}
]]></screen><para>you must call it through a link like:</para><screen><![CDATA[http://www.yoursite.com/modules.php?mop=modload
]]><![CDATA[&name=The_Web_Ring&file=index&func=func-one
]]></screen><para>If your function needs to have parameters (see <xref linkend="PHP-functions">), your switch will look like:</para><screen><![CDATA[switch($func) {
]]><![CDATA[ case "func-one":
]]><![CDATA[ funct-one($xid, $xname);
]]><![CDATA[ break;
]]><![CDATA[}
]]></screen><para>and your link will have to be:</para><screen><![CDATA[http://www.yoursite.com/modules.php?mop=modload
]]><![CDATA[&name=The_Web_Ring&file=index&func=func-one&xid=$xid&xname=$xname
]]></screen><para>See also the ADDONS-MODULES file that came with your <application>PHP-Nuke</application> package.</para></sect2>
</sect1>
<sect1 id="sql-syntax"><title>The syntax of SQL code</title><para>Aiming at making <application>PHP-Nuke</application> compatible with more databases, the SQL syntax<indexterm><primary>syntax</primary></indexterm> has been transformed to functions, in order to achieve a standard syntax<indexterm><primary>syntax</primary></indexterm> that is independent of the database used. For convenience, let us recall the file sql_layer.<indexterm><primary>layer</primary></indexterm>php in a somewhat cleaned-up version: </para><screen>
sql_connect($host, $user, $password, $db) <co id="login">
sql_logout($id) <co id="disconnect">
sql_query($query, $id) <co id="query">
sql_num_rows($res) <co id="numrows">
sql_fetch_row(&$res, $nr) <co id="fetchrows">
sql_fetch_array(&$res, $nr) <co id="fetcharray">
sql_fetch_object(&$res, $nr) <co id="fetchobject">
sql_free_result($res) <co id="freeresult">
</screen>
<calloutlist>
<callout arearefs="login">
<para>
Log into the DB.
</para>
</callout>
<callout arearefs="disconnect">
<para>
Disconnect from the DB.
</para>
</callout>
<callout arearefs="query">
<para>
Query.
</para>
</callout>
<callout arearefs="numrows">
<para>
Number of Rows.
</para>
</callout>
<callout arearefs="fetchrows">
<para>
Fetch Rows.
</para>
</callout>
<callout arearefs="fetcharray">
<para>
Fetch Array.
</para>
</callout>
<callout arearefs="fetchobject">
<para>
Fetch Object.
</para>
</callout>
<callout arearefs="freeresult">
<para>
Free Result.
</para>
</callout>
</calloutlist>
<para>With this syntax you will be able to render all the modifications,<indexterm><primary>modifications</primary></indexterm> blocks or modules you create compatible to all the databases supported by PHP-Nuke, which are:</para><itemizedlist><listitem><para>MySQL<indexterm><primary>MySQL</primary></indexterm></para></listitem><listitem><para>mSQL<indexterm><primary>mSQL</primary></indexterm></para></listitem><listitem><para>PostgreSQL<indexterm><primary>PostgreSQL</primary></indexterm></para></listitem><listitem><para>PostgreSQL_local<indexterm><primary>PostgreSQL_local</primary></indexterm></para></listitem><listitem><para>ODBC<indexterm><primary>ODBC</primary></indexterm></para></listitem><listitem><para>ODBC_Adabas<indexterm><primary>ODBC_Adabas</primary></indexterm></para></listitem><listitem><para>Interbase<indexterm><primary>base</primary></indexterm></para></listitem><listitem><para>Sybase<indexterm><primary>base</primary></indexterm></para></listitem></itemizedlist><para>From version 6.5 and up, <application>PHP-Nuke</application> users the same abstraction layer of phpBB<indexterm><primary>phpBB</primary></indexterm> for compatibility reasons. It's very easy and highly tested. Normaly you make a query on MySQL like this:</para><screen><![CDATA[$sql = "SELECT uid, uname FROM nuke_users";
]]><![CDATA[$result = mysql_query($sql);
]]><![CDATA[list($uid, $uname) = mysql_fetch_row($result);
]]></screen><para>With the SQL abstraction layer on PHP-Nuke, you would declare $db as a global<indexterm><primary>global</primary></indexterm> variable and then write:</para><screen><![CDATA[$sql = "SELECT uid, uname FROM nuke_users";
]]><![CDATA[$result = $db->sql_query($sql);
]]><![CDATA[$row = $db->sql_fetchrow($result);
]]></screen><para>This will return the array $row[] with the results. If you want to work with more friendly names you should do this:</para><screen><![CDATA[$uid = $row[uid];
]]><![CDATA[$uname = $row[uname];
]]></screen><para>But it is much faster for you (and for the system) to use just the array values directly, ie:</para><screen><![CDATA[echo "Hello $row[uname], Welcome to my site!";
]]></screen><para>Note that there isn't any &quot;sql_fetch_array&quot;, the sql_fetch_row automaticaly will create the array with the results of your query.<indexterm><primary>query</primary></indexterm> </para><para>The old method using the file sql_layer.<indexterm><primary>layer</primary></indexterm>php and the variable $dbi is now deprecated.<indexterm><primary>deprecated</primary></indexterm> It works for compatibility reasons, but we strongly suggest to any developer making new modules or modifying a module to start using the new method. See also the ADDONS-MODULES file that came with your <application>PHP-Nuke</application> package.</para></sect1>
<sect1 id="mysql-frontend"><title>MySQL Front, how to administer a MySQL DB from <productname>Windows</productname> </title><para>Mysql Front is a client for <productname>Windows</productname> that allows for the management to manage a local or remote DB through a client interface.<indexterm><primary>interface</primary></indexterm> Since we consider <application>PHP-Nuke</application> to be more aproppriate and flexible tool for this task, we would like to focus our attention a little on a functionality<indexterm><primary>functionality</primary></indexterm> of MySQLFront that on PHPMyAdmin has shown itself to be little reliable. That is the ability to load,<indexterm><primary>load</primary></indexterm> import and export DBs of great dimensions without losing data or getting errors.</para><para>In this section we will limit ourselves in analyzing the connection phase,<indexterm><primary>phase</primary></indexterm> the import and upload.<indexterm><primary>upload</primary></indexterm></para><para>Connection (<xref linkend="fig-mysqlfront-connection">): Clicking on File&lyxarrow;Connection, we will get an interface in which we are asked to enter the host, user and password.<indexterm><primary>password</primary></indexterm> If we have to use MySQLFront locally, we will leave the localhost entry untouched. </para><para>
<figure id="fig-mysqlfront-connection">
<title>
MySQL Front: Connection
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1205;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1205;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1205;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1205;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>MySQL Front: Connection</phrase>
</textobject>
<caption>
<para>MySQL Front: Connection</para>
</caption>
</mediaobject>
</figure>
</para><para>Download (or copy) of an existing DB: choose the database you wish to be exported and then click on &ldquo;Export Tables&rdquo; (fifth from the right, <xref linkend="fig-mysqlfront-export-tables">). Then choose a destination path for the database dump. As you may notice, the system,<indexterm><primary>system</primary></indexterm> through the use of flags, gives us even the possibility to choose individually those tables we want to import.</para><para>
<figure id="fig-mysqlfront-export-tables">
<title>
MySQL Front: export tables
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1206;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1206;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1206;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1206;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>MySQL Front: export tables</phrase>
</textobject>
<caption>
<para>MySQL Front: export tables</para>
</caption>
</mediaobject>
</figure>
</para><para>Upload of a DB: clicking on the SQL Query button (<xref linkend="fig-mysqlfront-SQL-query">), an interface appears that allows us to carry out the upload of an existing database.<indexterm><primary>base</primary></indexterm> It suffices to click on the symbol of the open folder, choose the database<indexterm><primary>base</primary></indexterm> dump and click on the button that looks&rdquo;Play&rdquo;-like button. Before starting this operation will have to select the destination database.<indexterm><primary>base</primary></indexterm></para><para>
<figure id="fig-mysqlfront-SQL-query">
<title>
MySQL Front: SQL Query
</title>
<mediaobject>
<![ %output.print.png; [
<imageobject>
<imagedata fileref="./images/&graph1207;.png" format="PNG">
</imageobject>
]]>
<![ %output.print.pdf; [
<imageobject>
<imagedata fileref="&graph1207;.pdf" format="PDF" scale="100">
</imageobject>
]]>
<![ %output.print.eps; [
<imageobject>
<imagedata fileref="./images/&graph1207;.eps" format="EPS">
</imageobject>
]]>
<![ %output.print.bmp; [
<imageobject>
<imagedata fileref="&graph1207;.bmp" format="BMP">
</imageobject>
]]>
<textobject>
<phrase>MySQL Front: SQL Query</phrase>
</textobject>
<caption>
<para>MySQL Front: SQL Query</para>
</caption>
</mediaobject>
</figure>
</para></sect1>
<sect1 id="foxserv"><title>Foxserv, making <application>PHP-Nuke</application> work on <productname>Windows</productname> Systems</title><para>There exists an application that installs <acronym>PHP</acronym> + MySQL + Apache in a simple and fast way, configuring your operating system to emulate a local Web server.<indexterm><primary>server</primary></indexterm> This is very useful, as it allows us to experiment with <application>PHP-Nuke</application> and our modifications locally. </para><para>The software is called Foxserv, has reached version 3.0, but I recommend using version 2.0 which is much easier to use.</para><para>The installation is very simple, it is enough to launch the FoxServ-2.0core.exe<indexterm><primary>FoxServ-2.0core.exe</primary></indexterm> file, proceed with the installation inserting any data (nothing is needed besides user and password of the DB) and then start using it!</para><para>When launching the foxserv control panel,<indexterm><primary>panel</primary></indexterm> you will have to activate apache and mysql, type in your browser the address http://localhost/and the web page will appear as if it were on any Internet server.<indexterm><primary>server</primary></indexterm></para><para>Suppose that you have installed everything in c:\foxserv.<indexterm><primary>foxserv</primary></indexterm> The <acronym>PHP</acronym> folders have to be inserted under the folder www. For example if we want to insert a nuke56 installation,<indexterm><primary>installation</primary></indexterm> we create the folder c:\foxserv<indexterm><primary>foxserv</primary></indexterm>\www\nuke56\ and load there all the content of the HTML folder of our <application>PHP-Nuke</application> (in the config.<indexterm><primary>config</primary></indexterm>php of <application>PHP-Nuke</application> we will leave &ldquo;localhost&rdquo; as our host, &ldquo;root<indexterm><primary>root</primary></indexterm>&rdquo; as user and nothing as password).</para><para>In order to reach PHPMyAdmin (even this is preinstalled), the address will be http://localhost/phpmyadmin/.</para><important>
<title>
Important note
</title>
<para>
The file php.ini (which is located, depending on the operating system, in c:\windows, c:\windows\system, c:\winnt or c:\winnt\system\) contains paths to a disc f:
</para>
</important>
<para>The only modification that you will have to make consists in:</para><itemizedlist><listitem><para>create a folder c:\temp</para></listitem><listitem><para>modify the parameter: session.<indexterm><primary>session</primary></indexterm>save_path = c:\temp. It must be c:\temp and not f:\foxserv etc.</para></listitem></itemizedlist><caution>
<title>
Attention
</title>
<para>
The folder &ldquo;php&rdquo; contains also a php.ini, but it is not the file that interests us.
</para>
</caution>
<para>FIXME: This section certainly needs updating! </para></sect1>
</chapter>
&appendix;
&bibliography;
&index;
</book>
View Git Blame Copy Permalink