fix #761 also see #762.
[phpeclipse.git] / net.sourceforge.phpeclipse.help / docbook-src / guide / src / en / user-manual / workspace.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 id="sec.workspace">
7   <title>Workspace</title>
8   <para>
9     Once you have installed &eclipse; and start it the first time &eclipse; asks you about selecting a workspace. The  (see <xref linkend="fig.select_workspace"/>. The default path for the workspace on a Windows system is <filename class="directory">C:\Documents and Settings\your_username\workspace</filename>. Even if you don't know what the workspace is good for, and even if you don't know whether this is a good place for a workspace you can safely accept this path with clicking <quote>OK</quote>.
10   </para>
11
12   <para>
13     It is also no problem to activate the <guibutton>Use this as default and do not ask again</guibutton>. You can always change your workspace and/or can activate to be asked again for a workspace when &eclipse; is starting.
14   </para>
15
16   <figure id="fig.select_workspace">
17     <title>Select a workspace</title>
18     <mediaobject>
19       <imageobject role="html">
20         <imagedata align="center" fileref="img/en/xo-002/select_a_workspace.png" format="PNG"/>
21       </imageobject>
22       <imageobject role="fo">
23         <imagedata align="center" fileref="img/en/xo-002/select_a_workspace.png" format="PNG" width="12cm"/>
24       </imageobject>
25     </mediaobject>
26   </figure>
27
28
29   <sect1 id="sec.change_workspace">
30     <title>Changing the workspace</title>
31     <para>
32       You can change the workspace after &eclipse; has started by clicking on
33       <menuchoice>
34         <guimenu>File</guimenu>
35         <guisubmenu>Switch Workspace...</guisubmenu>
36       </menuchoice> (see <xref linkend="fig.switch_workspace"/>
37       This opens a dialog (see <xref linkend="fig.workspace_dialog"/> where you can select an already existing workspace, or a new folder which should be used as a workspace.
38     </para>
39
40
41     <figure id="fig.switch_workspace">
42       <title>Switch a workspace</title>
43       <mediaobject>
44         <imageobject role="html">
45           <imagedata align="center" fileref="img/en/xo-002/switch_workspace.png" format="PNG"/>
46         </imageobject>
47         <imageobject role="fo">
48           <imagedata align="center" fileref="img/en/xo-002/switch_workspace.png" format="PNG" width="6cm"/>
49         </imageobject>
50       </mediaobject>
51     </figure>
52
53     <figure id="fig.workspace_dialog">
54       <title>Select a workspace</title>
55       <mediaobject>
56         <imageobject role="html">
57           <imagedata align="center" fileref="img/en/xo-002/workspace_dialog.png" format="PNG"/>
58         </imageobject>
59         <imageobject role="fo">
60           <imagedata align="center" fileref="img/en/xo-002/workspace_dialog.png" format="PNG" width="12cm"/>
61         </imageobject>
62       </mediaobject>
63     </figure>
64   </sect1>
65
66
67   <sect1 id="sec.activate_prompt_for_workspace">
68     <title>Activate the <quote>Select a workspace</quote> dialog</title>
69     <para>
70       In case you have deactivated the prompting for a workspace setting, you can activate it again by clicking on
71       <menuchoice>
72         <guimenu>Window</guimenu>
73         <guisubmenu>Preferences</guisubmenu>
74         <guimenuitem>General</guimenuitem>
75         <guimenuitem>Startup and Shutdown</guimenuitem>
76       </menuchoice> and then activating <guibutton>Prompt for workspace on startup</guibutton> (see <xref linkend="fig.activate_prompt_for_workspace"/>)
77     </para>
78
79
80     <figure id="fig.activate_prompt_for_workspace">
81       <title>Activate prompt for workspace</title>
82       <mediaobject>
83         <imageobject role="html">
84           <imagedata align="center" fileref="img/en/xo-002/activate_prompt_for_workspace.png" format="PNG"/>
85         </imageobject>
86         <imageobject role="fo">
87           <imagedata align="center" fileref="img/en/xo-002/activate_prompt_for_workspace.png" format="PNG" width="12cm"/>
88         </imageobject>
89       </mediaobject>
90     </figure>
91   </sect1>
92
93
94   <sect1 id="sec.choose_workspace">
95     <title>What workspace to choose for PHP</title>
96     <para>
97       So now I know how to select a workspace, but what is a good place for a workspace. I have different projects and/or have already existing files, have a already running webserver. So how does this all match?
98     </para>
99
100     <para>
101       So, as all roads lead to Rome there are several different methods which will be discussed in the following sections. But first, let us explain how the workspace directory will look like, as the structure of a workspace will always be the same (independent of where it is located).
102     </para>
103
104     <para>
105       Within the workspace folder there is a folder named <filename class="directory">.metadata</filename>, which we will, for simplicity, not discuss here. Besides this folder, &eclipse; will create additional folders for every project, independently whether the project is a PHP, Java or anything else project.
106     </para>
107
108
109     <sect2 id="sec.workspace_method_1">
110       <title>Workspace Method 1</title>
111       <para>
112         The workspace is set to be in the <filename class="directory">Documents and Settings</filename> folder and also the PHP-files are located within the workspace.
113       </para>
114
115       <para>
116         In this case we would have the following path: <filename class="directory">C:\Documents and Settings\Robert\workspace</filename>. When we have created a project (e.g. MyFirstPHPProject) through &eclipse; and create a PHP-file (e.g. index.php) we would see the file as: <filename class="directory">C:\Documents&nbsp;and&nbsp;Settings\Robert\workspace\MyFirstPHPProject\index.php</filename>.
117       </para>
118
119
120       <sect3 id="sec.swm_1_change_docroot">
121         <title>Configure Web Server by changing Document Root</title>
122         <para>
123           Given that our webserver is installed in a different directory and also the &docroot; points to a different directory, we have to change the &docroot; path to our <filename class="directory">workspace</filename> folder (see <xref linkend="sec.xampp_change_doc_root"/>), which would be the following in our example:<filename class="directory">C:\Documents&nbsp;and&nbsp;Settings\Robert\workspace</filename>
124         </para>
125
126         <para>
127           As the project's default &docroot; is set to the current workspace, we do not need to change anything.
128         </para>
129
130         <para>
131           In this case the file <filename>myFirstFile.php</filename> can be called by the web browser with the following URL: <ulink url="http://localhost/MyFirstPHPProject/myFirstFile.php"></ulink>
132         </para>
133
134 <!--
135         <para>
136           You also have to set <quote>DocumentRoot</quote> within the <quote>PHP Project Settings</quote>. Open the context menu by right clicking on <quote>MyFirstPHPProjecty</quote> within the <quote>Navigator View</quote>and click on <quote>Properties</quote>, which opens the properties dialog for the project. Click on <quote>PHP Project Settings</quote> and set the <quote>DocumentRoot</quote> according <xref linkend="fig.set_document_root_1"/>.
137         </para>
138
139         <figure id="fig.set_document_root_1">
140           <title>Change Document Root</title>
141           <mediaobject>
142             <imageobject role="html">
143               <imagedata align="center" fileref="img/en/xo-002/set_document_root_for_project_1.png" format="PNG"/>
144             </imageobject>
145             <imageobject role="fo">
146               <imagedata align="center" fileref="img/en/xo-002/set_document_root_for_project_1.png" format="PNG" width="12cm"/>
147             </imageobject>
148           </mediaobject>
149         </figure>
150 -->
151       </sect3>
152
153       <sect3 id="sec.swm_1_add_alias">
154         <title>Configure Web Server by adding Alias</title>
155         <para>
156           As an alternative to changing the &docroot; we can add an alias (see <xref linkend="sec.xampp_add_alias"/>) to the web server's configuration file. In this case we also would have to change the localhost setting within our project properties.
157         </para>
158
159         <figure id="fig.set_localhost">
160           <title>Set localhost when using Alias</title>
161           <mediaobject>
162             <imageobject role="html">
163               <imagedata align="center" fileref="img/en/xo-002/set_document_root_for_project_2.png" format="PNG"/>
164             </imageobject>
165             <imageobject role="fo">
166               <imagedata align="center" fileref="img/en/xo-002/set_document_root_for_project_2.png" format="PNG" width="12cm"/>
167             </imageobject>
168           </mediaobject>
169         </figure>
170       </sect3>
171     </sect2>
172
173
174     <sect2 id="sec.workspace_method_2">
175       <title>Workspace Method 2</title>
176       <para>
177         The workspace path is the same as the &docroot; path.
178       </para>
179
180       <para>
181         In some cases (or maybe in many?) people which tries to work with &phpeclipse; have already set up a working Apache and PHP environment. Which means, they have already a htdocs directory anywhere on their local machine, and they have already some PHP-files within the existing htdocs folder. And they don't want to move all their files into the &eclipse; workspace folder. One way to accomplish this would be to set the &eclipse; workspace to the  already existing htdocs folder.
182       </para>
183
184       <para>
185         For example you have set up XAMPP and your &docroot; path is the XAMPP default: <filename class="directory">C:\Program&nbsp;Files\apachefriends\xampp\htdocs</filename>, then your appropriate workspace path should be one level less: <filename class="directory">C:\Program&nbsp;Files\apachefriends\xampp</filename>. Now you create a new PHP project and name it <quote>htdocs</quote>. &phpeclipse; will automatically add all files within the <filename>htdocs</filename> folder to the project. Just adjust the project's <quote>DocumentRoot</quote> setting as described in <xref linkend="sec.swm_1_change_docroot"/>.
186       </para>
187     </sect2>
188
189
190     <sect2 id="sec.workspace_method_3">
191       <title>Workspace Method 3</title>
192       <para>
193         The workspace is set to be in the <filename class="directory">Documents and Settings</filename> folder and the PHP-files are in a different folder.
194       </para>
195
196       <para>
197         As we have seen how we can work with method 1 and method 2, there is another method of setting up your workspace and project which also allows you to hold the &eclipse; workspace and your PHP-files separated.
198       </para>
199
200       <para>
201         For example your workspace path is <filename class="directory">C:\Documents and Settings\Robert\workspace</filename> and your current &docroot; is <filename class="directory">C:\Program&nbsp;Files\apachefriends\xampp\htdocs</filename>. See <xref linkend="sec.add_file_by_linking"/> how to set up a project for this case.
202       </para>
203     </sect2>
204
205 <!--
206     <sect2 id="sec.create_new_workspace">
207       <title>Create a New Workspace</title>
208       <para>
209
210       </para>
211     </sect2>
212 -->
213   </sect1>
214 </chapter>