net.sourceforge.phpeclipse.help/docbook-src/guide/src/en/user-manual/project.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!-- jEdit buffer-local properties: -->
   3 <!-- :indentSize=2:noTabs=true: -->
   4 <!-- :xml.root=docmaster.xml: -->
   5
   6 <chapter>
   7   <title>Project</title>
   8   <para>
   9     So, when finished with setting up a workspace, we can go for our first PHP project. This is a necessary step, because a workspace alone will not help. We also need to set up a project within a workspace. As we want to work with PHP we will create a PHP project.
  10   </para>
  11
  12   <sect1 id="sec.project_creation">
  13     <title>Create a project</title>
  14     <para>
  15       For creating a project klick on
  16       <menuchoice>
  17         <guimenu>File</guimenu>
  18         <guisubmenu>New</guisubmenu>
  19         <guisubmenu>Project...</guisubmenu>
  20       </menuchoice> (see <xref linkend="fig.create_new_project"/>). This will open a project creation wizard dialog (see <xref linkend="fig.select_a_wizard"/>). Now click on <quote>PHP Project</quote> under the PHP tree entry as you can see in <xref linkend="fig.php_project_name"/>. When you click on <guibutton>Next &gt;</guibutton> the PHP Project dialog will be shown, where you can input a name for your new PHP Project. In our example we choose the name <quote>MyFirstPHPProject</quote>. Now, just click on <guibutton>Finish</guibutton>, and your project will be created. Now you should see your project within the Navigator pane (see x
  21     </para>
  22
  23     <figure id="fig.create_new_project">
  24       <title>Create a new projec</title>
  25       <mediaobject>
  26         <imageobject role="html">
  27           <imagedata align="center" fileref="img/en/xo-002/create_new_project_1.png" format="PNG"/>
  28         </imageobject>
  29         <imageobject role="fo">
  30           <imagedata align="center" fileref="img/en/xo-002/create_new_project_1.png" format="PNG" width="12cm"/>
  31         </imageobject>
  32       </mediaobject>
  33     </figure>
  34
  35
  36     <figure id="fig.select_a_wizard">
  37       <title>Select a wizard</title>
  38       <mediaobject>
  39         <imageobject role="html">
  40           <imagedata align="center" fileref="img/en/xo-002/create_new_project_2.png" format="PNG"/>
  41         </imageobject>
  42         <imageobject role="fo">
  43           <imagedata align="center" fileref="img/en/xo-002/create_new_project_2.png" format="PNG" width="12cm"/>
  44         </imageobject>
  45       </mediaobject>
  46     </figure>
  47
  48
  49     <figure id="fig.php_project_name">
  50       <title>Name your PHP Project</title>
  51       <mediaobject>
  52         <imageobject role="html">
  53           <imagedata align="center" fileref="img/en/xo-002/create_new_project_3.png" format="PNG"/>
  54         </imageobject>
  55         <imageobject role="fo">
  56           <imagedata align="center" fileref="img/en/xo-002/create_new_project_3.png" format="PNG" width="12cm"/>
  57         </imageobject>
  58       </mediaobject>
  59     </figure>
  60
  61
  62     <figure id="fig.php_project">
  63       <title>The new PHP Project within the Navigator pane</title>
  64       <mediaobject>
  65         <imageobject role="html">
  66           <imagedata align="center" fileref="img/en/xo-002/create_new_project_4.png" format="PNG"/>
  67         </imageobject>
  68         <imageobject role="fo">
  69           <imagedata align="center" fileref="img/en/xo-002/create_new_project_4.png" format="PNG" width="8cm"/>
  70         </imageobject>
  71       </mediaobject>
  72     </figure>
  73   </sect1>
  74
  75
  76   <sect1 id="sec.add_files_to_projects">
  77     <title>Adding files to the project</title>
  78     <para>
  79       Now, as we have created a PHP project we need some PHP files in it. The following sections will explain the different aspects about adding a file to your project.
  80     </para>
  81
  82     <sect2 id="sec.add_file_simple">
  83       <title>Adding a simple file</title>
  84       <para>
  85         Per se, there are two different methods of adding a file to your project. Both are available through the <quote>File</quote> menu.
  86       </para>
  87
  88       <para>
  89         The first method is to add a <quote>simple</quote> file to your project by clicking on <menuchoice>
  90           <guimenu>File</guimenu>
  91           <guisubmenu>New</guisubmenu>
  92           <guisubmenu>File</guisubmenu>
  93         </menuchoice> (see <xref linkend="fig.add_file_menu_file"/>). This will open the appropriate <quote>New File</quote> dialog. Input the name for that file (with the extension <quote>php</quote>), and click on <guibutton>Finish</guibutton>. This will add the new file to the <quote>Navigator</quote> pane, and opens an editor view.
  94       </para>
  95
  96
  97       <figure id="fig.add_file_menu_file">
  98         <title>Adding a simple file to the project</title>
  99         <mediaobject>
 100           <imageobject role="html">
 101             <imagedata align="center" fileref="img/en/xo-002/add_file_to_project_1.png" format="PNG"/>
 102           </imageobject>
 103           <imageobject role="fo">
 104             <imagedata align="center" fileref="img/en/xo-002/add_file_to_project_1.png" format="PNG" width="10cm"/>
 105           </imageobject>
 106         </mediaobject>
 107       </figure>
 108
 109
 110       <figure id="fig.new_file_dialog">
 111         <title>The <emphasis>New File</emphasis> Dialog</title>
 112         <mediaobject>
 113           <imageobject role="html">
 114             <imagedata align="center" fileref="img/en/xo-002/add_file_to_project_2.png" format="PNG"/>
 115           </imageobject>
 116           <imageobject role="fo">
 117             <imagedata align="center" fileref="img/en/xo-002/add_file_to_project_2.png" format="PNG" width="12cm"/>
 118           </imageobject>
 119         </mediaobject>
 120       </figure>
 121
 122
 123       <figure id="fig.new_file_in_navigator">
 124         <title>The new file in the <emphasis>Navigator</emphasis> view</title>
 125         <mediaobject>
 126           <imageobject role="html">
 127             <imagedata align="center" fileref="img/en/xo-002/add_file_to_project_3.png" format="PNG"/>
 128           </imageobject>
 129           <imageobject role="fo">
 130             <imagedata align="center" fileref="img/en/xo-002/add_file_to_project_3.png" format="PNG" width="6cm"/>
 131           </imageobject>
 132         </mediaobject>
 133       </figure>
 134
 135
 136       <figure id="fig.new_file_in_editor">
 137         <title>The new file opened in PHP editor</title>
 138         <mediaobject>
 139           <imageobject role="html">
 140             <imagedata align="center" fileref="img/en/xo-002/add_file_to_project_4.png" format="PNG"/>
 141           </imageobject>
 142           <imageobject role="fo">
 143             <imagedata align="center" fileref="img/en/xo-002/add_file_to_project_4.png" format="PNG" width="12cm"/>
 144           </imageobject>
 145         </mediaobject>
 146       </figure>
 147     </sect2>
 148
 149
 150     <sect2 id="sec.add_file_php">
 151       <title>Add a PHP file to the project</title>
 152       <para>
 153         The second method of adding a PHP file to your project is through
 154         <menuchoice>
 155           <guimenu>File</guimenu>
 156           <guisubmenu>New</guisubmenu>
 157           <guisubmenu>PHP File</guisubmenu>
 158         </menuchoice> (see <xref linkend="fig.add_file_menu_phpfile"/>). This will open a <quote>New PHP file</quote> dialog with a default File name entry of <quote>file.php</quote> (see <xref linkend="fig.new_phpfile_dialog"/>). We change the file name to <filename>mySecondFile.php</filename> (see <xref linkend="fig.new_phpfile_dialog_change_name"/>) and click on <guibutton>Finish</guibutton>.
 159       </para>
 160
 161
 162       <para>
 163         This also will add a PHP file to your project as you can see in the <emphasis>Navigator</emphasis> view (see <xref linkend="fig.new_phpfile_in_navigator"/>), and it also opens this new file within the PHP editor (see <xref linkend="fig.new_phpfile_in_navigator"/>) as it was done in <xref linkend="sec.add_file_simple"/>.
 164       </para>
 165
 166       <para>
 167         But there is obviously a difference. In opposite to <filename>myFirstFile.php</filename> which is a real empty file, <filename>mySecondFile.php</filename> has some text in it (see <xref linkend="fig.new_phpfile_in_editor"/>). The file we just created is filled with a <quote>template</quote>. <!-- todo: link to the template config section once this is written -->
 168       </para>
 169
 170       <para>
 171         The difference is only at creation time. The files themselfs, when created, do not differ in any sense.
 172       </para>
 173
 174       <para id="para.absolute_file_path">
 175         When we look at file system level, the absolute path of the files we just created are in respect of the current workspace, in general: <filename>workspace_path/project/file.php</filename>. For example if you have accepted the default workspace when you started eclipse (and your username is Robert):
 176         <itemizedlist>
 177           <listitem>
 178             <para>
 179               <emphasis>myFirstFile.php</emphasis>: <filename>C:/Dokuments&nbsp;and&nbsp;Settings/Robert/workspace/MyFirstPHPProject/myFirstFile.php</filename>
 180             </para>
 181           </listitem>
 182           <listitem>
 183             <para>
 184               <emphasis>mySecondFile.php</emphasis>: <filename>C:/Dokuments&nbsp;and&nbsp;Settings/Robert/workspace/MyFirstPHPProject/mySecondFile.php</filename>
 185             </para>
 186           </listitem>
 187         </itemizedlist>
 188       </para>
 189
 190       <note>
 191       <para>
 192         The importance of knowing the absolute path is when the web server comes into account. As you want to test the program you have written, the web server needs access to your PHP files. This could be accomplished either when you set your web server's document root to point at your current workspace, or set your workspace to the currect web server's document root. <!-- todo point to the xammp installation section -->
 193       </para>
 194
 195       <para>
 196         But there is a third way, which will make things easier, as you can leave the workspace wherever you want, and also do not need to change the web server's document root.
 197       </para>
 198       </note>
 199
 200       <figure id="fig.add_file_menu_phpfile">
 201         <title>Adding a PHP file to the project</title>
 202         <mediaobject>
 203           <imageobject role="html">
 204             <imagedata align="center" fileref="img/en/xo-002/add_phpfile_to_project_1.png" format="PNG"/>
 205           </imageobject>
 206           <imageobject role="fo">
 207             <imagedata align="center" fileref="img/en/xo-002/add_phpfile_to_project_1.png" format="PNG" width="12cm"/>
 208           </imageobject>
 209         </mediaobject>
 210       </figure>
 211
 212
 213       <figure id="fig.new_phpfile_dialog">
 214         <title>The <emphasis>New PHP file</emphasis>dialog</title>
 215         <mediaobject>
 216           <imageobject role="html">
 217             <imagedata align="center" fileref="img/en/xo-002/add_phpfile_to_project_2.png" format="PNG"/>
 218           </imageobject>
 219           <imageobject role="fo">
 220             <imagedata align="center" fileref="img/en/xo-002/add_phpfile_to_project_2.png" format="PNG" width="12cm"/>
 221           </imageobject>
 222         </mediaobject>
 223       </figure>
 224
 225
 226       <figure id="fig.new_phpfile_dialog_change_name">
 227         <title>Change the name to what you like</title>
 228         <mediaobject>
 229           <imageobject role="html">
 230             <imagedata align="center" fileref="img/en/xo-002/add_phpfile_to_project_3.png" format="PNG"/>
 231           </imageobject>
 232           <imageobject role="fo">
 233             <imagedata align="center" fileref="img/en/xo-002/add_phpfile_to_project_3.png" format="PNG" width="12cm"/>
 234           </imageobject>
 235         </mediaobject>
 236       </figure>
 237
 238
 239       <figure id="fig.new_phpfile_in_navigator">
 240         <title>The new PHP file in the &navview;</title>
 241         <mediaobject>
 242           <imageobject role="html">
 243             <imagedata align="center" fileref="img/en/xo-002/add_phpfile_to_project_4.png" format="PNG"/>
 244           </imageobject>
 245           <imageobject role="fo">
 246             <imagedata align="center" fileref="img/en/xo-002/add_phpfile_to_project_4.png" format="PNG" width="6cm"/>
 247           </imageobject>
 248         </mediaobject>
 249       </figure>
 250
 251
 252       <figure id="fig.new_phpfile_in_editor">
 253         <title>The new PHP file opened in PHP editor</title>
 254         <mediaobject>
 255           <imageobject role="html">
 256             <imagedata align="center" fileref="img/en/xo-002/add_phpfile_to_project_5.png" format="PNG"/>
 257           </imageobject>
 258           <imageobject role="fo">
 259             <imagedata align="center" fileref="img/en/xo-002/add_phpfile_to_project_5.png" format="PNG" width="12cm"/>
 260           </imageobject>
 261         </mediaobject>
 262       </figure>
 263     </sect2>
 264
 265
 266     <sect2 id="sec.add_file_existing">
 267       <title>Add existing files to the project</title>
 268       <para>
 269         There are generally two ways to add files, which already exists anywhere on your file system, to a project<footnote><para>Every file which you want to open and handle with &phpeclipse; needs to be within a project.</para></footnote>.
 270       </para>
 271
 272       <sect3 id="sec.add_file_by_import">
 273         <title>Import Files</title>
 274         <para>
 275           You can import files from anywhere on your local machine by eclipse itself via      <menuchoice>
 276             <guimenu>File</guimenu>
 277             <guisubmenu>Import...</guisubmenu>
 278           </menuchoice> (see <xref linkend="fig.file_import_1"/>) or by manually copying the files via the file system into your project folder (see <xref linkend="para.absolute_file_path"/>). In fact the way via <emphasis>Import...</emphasis> is more convenient.
 279         </para>
 280
 281         <para>
 282           But this method only makes a copy of existing files, and doesn't disburden you from changing the web server's &docroot;. Especially if the files you have currently imported to your workspace are located on your current web server's &docroot;.
 283         </para>
 284
 285         <para>
 286           In this case it would be easier to set the workspace to the current web server's &docroot;, or do as described in the following section <xref linkend="sec.add_file_by_linking"/>.
 287         </para>
 288
 289
 290         <figure id="fig.file_import_1">
 291           <title>Import Files into Project</title>
 292           <mediaobject>
 293             <imageobject role="html">
 294               <imagedata align="center" fileref="img/en/xo-002/file_import_1.png" format="PNG"/>
 295             </imageobject>
 296             <imageobject role="fo">
 297               <imagedata align="center" fileref="img/en/xo-002/file_import_1.png" format="PNG" width="10cm"/>
 298             </imageobject>
 299           </mediaobject>
 300         </figure>
 301
 302       </sect3>
 303
 304
 305       <sect3 id="sec.add_file_by_linking">
 306         <title>Link Folders</title>
 307         <para>
 308           Indeed, this should be the best option if you want to have independence between a eclipse workspace and the web server's &docroot;.
 309         </para>
 310
 311         <para>
 312           <itemizedlist>
 313             <listitem>
 314               <para>
 315                 Create a new project (e.g. <quote>MyLinkedPHPProject</quote>).
 316               </para>
 317             </listitem>
 318             <listitem>
 319               <para>
 320                 Right click on this project within the <quote>Navigator View</quote> to open the context menu and click on.
 321                 <menuchoice>
 322                   <guimenu>New</guimenu>
 323                   <guisubmenu>Folder</guisubmenu>
 324                 </menuchoice> (see <xref linkend="fig.linked_project_1"/>).
 325               </para>
 326             </listitem>
 327             <listitem>
 328               <para>
 329                 Click on <guibutton>Advanced &gt;&gt;</guibutton> and enable <guibutton>Link to folder in the file system</guibutton> (see <xref linkend="fig.linked_project_2"/>).
 330               </para>
 331             </listitem>
 332             <listitem>
 333               <para>
 334                 Now you can either manually enter the path or browse to the folder which is to link. In the example we input <filename class="directory">C:\Program&nbsp;Files\apachefriends\xampp\htdocs</filename>, and click on <guibutton>Finish</guibutton>. The &navview; should now look like (see <xref linkend="fig.linked_project_3"/>).
 335               </para>
 336             </listitem>
 337             <listitem>
 338               <para>
 339                 At last we have to set the correct &docroot; (which is <filename class="directory">C:\Program&nbsp;Files\apachefriends\xampp\htdocs</filename>) within the project properties as shown in <xref linkend="fig.linked_project_4"/>
 340               </para>
 341             </listitem>
 342           </itemizedlist>
 343         </para>
 344
 345
 346         <figure id="fig.linked_project_1">
 347           <title>Add a Folder to Project</title>
 348           <mediaobject>
 349             <imageobject role="html">
 350               <imagedata align="center" fileref="img/en/xo-002/linked_project_1.png" format="PNG"/>
 351             </imageobject>
 352             <imageobject role="fo">
 353               <imagedata align="center" fileref="img/en/xo-002/linked_project_1.png" format="PNG" width="8cm"/>
 354             </imageobject>
 355           </mediaobject>
 356         </figure>
 357
 358
 359         <figure id="fig.linked_project_2">
 360           <title>Create a Link Folder</title>
 361           <mediaobject>
 362             <imageobject role="html">
 363               <imagedata align="center" fileref="img/en/xo-002/linked_project_2.png" format="PNG"/>
 364             </imageobject>
 365             <imageobject role="fo">
 366               <imagedata align="center" fileref="img/en/xo-002/linked_project_2.png" format="PNG" width="12cm"/>
 367             </imageobject>
 368           </mediaobject>
 369         </figure>
 370
 371
 372         <figure id="fig.linked_project_3">
 373           <title>The &navview; with the new Project</title>
 374           <mediaobject>
 375             <imageobject role="html">
 376               <imagedata align="center" fileref="img/en/xo-002/linked_project_3.png" format="PNG"/>
 377             </imageobject>
 378             <imageobject role="fo">
 379               <imagedata align="center" fileref="img/en/xo-002/linked_project_3.png" format="PNG" width="4cm"/>
 380             </imageobject>
 381           </mediaobject>
 382         </figure>
 383
 384
 385         <figure id="fig.linked_project_4">
 386           <title>Change the Project's DocumentRoot Setting</title>
 387           <mediaobject>
 388             <imageobject role="html">
 389               <imagedata align="center" fileref="img/en/xo-002/linked_project_4.png" format="PNG"/>
 390             </imageobject>
 391             <imageobject role="fo">
 392               <imagedata align="center" fileref="img/en/xo-002/linked_project_4.png" format="PNG" width="12cm"/>
 393             </imageobject>
 394           </mediaobject>
 395         </figure>
 396
 397       </sect3>
 398     </sect2>
 399   </sect1>
 400 </chapter>