egroupware/doc/sgml/devinst.sgml

<chapter id="devinstall">
	<title>Installing your application</title>
	
	<simplesect>
		<title>Overview</title>
	
		<para>It is fairly simple to add and delete applications to/from phpGroupWare.</para>
	</simplesect>
	<simplesect>
		<title>Automatic features</title>
		<para>
			To make things easy for developers we go ahead and load the following files.
  			<itemizedlist>
			<listitem><para> <filename>appname/inc/functions.inc.php</filename> - This file should include
					all your application specific functions.</para></listitem>
 			<listitem><para> <filename>appname/inc/header.inc.php</filename> - This file is loaded by
 					<classname>$phpgw->common->header</classname> just after the system header/navbar,
 					and allows developers to use it for whatever they need to load.</para></listitem>
  			<listitem><para> <filename>appname/inc/footer.inc.php</filename> - This file is loaded by
  					<classname>$phpgw->common->footer</classname> just before the system footer,
  					allowing developers to close connections and whatever else they need.</para></listitem>
  			</itemizedlist>  			
		</para>
	</simplesect>
	<simplesect>
		<title>Adding files, directories and icons.</title>
		<para>
			You will need to create the following directories for your code
  			(replace 'appname' with your application name)
  			<programlisting>
 `-- appname
      `-- images
      |   `-- navbar.gif
      `-- inc
      |   |-- functions.inc.php
      |   |-- header.inc.php
      |   |-- footer.inc.php
      |   |-- preferences.inc.php
      |   `-- admin.inc.php
      `-- templates
          `-- default
  			</programlisting>
  		</para>
	</simplesect>
	<simplesect>
		<title>Making phpGroupWare aware of your application</title>
		<para>
			 To make the application aware of your application, add your application details to the applications table. This can be done via the GUI administration screen, or via a SQL script.
<programlisting>
  insert into applications (app_name, app_title, app_enabled) values ('appname', 'The App name', 1);
</programlisting>
		</para>
	</simplesect>
	<simplesect>
		<title>Hooking into Administration page</title>
		<para>
			When a user goes to the Administration page, it stats appname/inc/admin.inc.php
			for each application that is enabled, in alphabetical order of application title.
			If the file exists, it is include()d in the hopes it will display a selection of
			links to configure that application.

			Simple Example:
			<programlisting>
&lt;?php
  $img = "/" . $appname . "/images/navbar.gif";
  section_start("My Application",$img);
  echo "&lt;a HREF=\"" . $phpgw->link("myAdminPage.php") . "\"&gt;";
  echo lang("Change myApp settings") . "&lt;/a&gt;";
  section_end();
?&gt;
			</programlisting>
			Look at headlines/inc/admin.inc.php and admin/inc/admin.inc.php for more examples.

			Things to note:
			<itemizedlist mark=bullet>
			<listitem><para>Links are relative to the <filename>admin/index.php</filename> file, not your
				 application's base directory. (so use <classname>$appname</classname> in your
				 <classname>link()</classname> calls)</para></listitem>
			<listitem><para>The file is brought in with include() so be careful to not pollute the name-space
				too much</para></listitem>
			</itemizedlist>
			The standard $phpgw and $phpgw_info variables are in-scope, as is $appname
			which corresponds to the application name in the path.

			There are 2 functions to coordinate the display of each application's links,
			section_start() and section_end()
		</para>
	</simplesect>
	<simplesect>
		<title>section_start</title>
		<para>
			<classname>section_start($title,$icon_url)</classname>
			starts the section for your application. <classname>$title</classname> is passed through
			<classname>lang()</classname>
			for you. <classname>$icon_url</classname> should be page-relative to admin/index.php or
			an absolute URL.
		</para>
	</simplesect>
	<simplesect>
		<title>section_end</title>
		<para>
			<classname>section_end()</classname> closes the section that was started with section_start().
		</para>
	</simplesect>
	<simplesect>
		<title>Hooking into Preferences page</title>
		<para>
			The mechanism to hook into the preferences page is identical to the one used to
			hook into the administration page, however it looks for
			<filename>appname/inc/preferences.inc.php</filename> instead of
			<filename>appname/inc/admin.inc.php</filename>. The same functions and variables are defined.
		</para>
	</simplesect>
</chapter>