174 | | Server Tier. This tier runs the MGOS server. Fusion is not integrated into this tier. |
175 | | Web Extensions Tier. This tier runs with a Web Server. Fusion is installed in this tier and makes use of the MGOS Web Extensions API to implement some functionality. |
176 | | Client Tier. This tier runs in the client's web browser. Most of Fusion exists in this tier, and it completely replaces the existing MGOS client tier (known as the AJAX viewer). |
177 | | |
178 | | Diagram 1 shows how Fusion integrates into the MGOS Tiers. The blue blocks are new Fusion components and the light grey blocks are existing MGOS components. |
179 | | |
180 | | The Fusion Server components work directly with the MGOS PHP API to implement specific functionality such as buffering features and working with selections. |
181 | | |
182 | | The Fusion JavaScript API and widgets are installed with the MGOS Web Tier, but they are actually loaded up to and executed in the Client Tier. |
183 | | WebLayouts, HTML and Widgets |
184 | | |
185 | | The API and widgets are linked to specific HTML elements within an HTML page through the WebLayout XML document. A widget is the executable code (javascript class) that is loaded when Fusion identifies an HTML element id and WebLayout command name that are the same. The Action of the WebLayout Command identifies the exact javascript file to be loaded and the javascript object that needs to be instantiated to create a functional widget. The runtime instance of the javascript object is the widget. |
186 | | |
187 | | When the runtime instance is created, it uses the HTML element id to determine where in the HTML page it should display its user interface. Any custom configuration for the widget is placed in the WebLayout Command XML block as sub tags (each widget has its own list of what customization is possible, see the Command API Reference for details). |
188 | | |
189 | | If you are customizing the look and feel of a single widget by overriding the CSS styling for the widget, this is normally done by using the #<id> syntax to limit your changes to that specific widget. |
190 | | Understanding WebLayouts |
191 | | |
192 | | A Web Layout is an XML document that provides control over the appearance and behaviour of elements of a Fusion application. It consists of blocks of XML that control various aspects of a Fusion application. The root element of a Web Layout document is always <WebLayout>. |
193 | | The following elements may exist within the WebLayout element: |
194 | | Map |
195 | | ToolBar |
196 | | CommandSet |
197 | | Map |
198 | | |
199 | | The Map block is optional and may occur 0 or more times. It defines per-Map metadata that cannot be stored with the Map in any other way. The Map block contains the following elements: |
200 | | ResourceId. The ResourceId tag identifies the Map to which this metadata is relevant. |
201 | | Links. Links are used to identify external URLs that contain information related to groups or layers. Links are discussed in more detail below. |
202 | | LayerEvents. LayerEvents are used to make changes to the visibility of related groups and/or layers when a layer or group changes visibility. LayerEvents are described in more detail below. |
203 | | Links |
204 | | |
205 | | The Links block can contain any number of Group and Layer blocks. Group and Layer blocks contain identical tags: |
206 | | Name. This tag is used to identify a Group or Layer by its name. |
207 | | Url. This tag is the href that is opened when the user wants to get information about the Group or Layer. It may be absolute or relative, but if it is relative, it is relative to the application. |
208 | | |
209 | | Example Links block: |
210 | | |
211 | | <Links> |
212 | | <Group> |
213 | | <Name>Transportation</Name> |
214 | | <Url>http://localhost/transportation.html</Url> |
215 | | </Group> |
216 | | <Layer> |
217 | | <Name>Parcels</Name> |
218 | | <Url>http://localhost/parcels.html</Url> |
219 | | </Layer> |
220 | | </Links> |
221 | | LayerEvents |
222 | | |
223 | | The LayerEvents block can contain any number of Layer and/or Group blocks. A Layer or Group block identifies the Layer or Group to which it applies in a Name tag. There are two additional blocks that control what happens when the Layer or Group changes visibility. The OnEnable block is used when the Layer or Group becomes visible, and the OnDisable block is used when the Layer or Group becomes hidden. Both blocks have the same structure. They contain any number of Layer or Group blocks that contain a Name tag (which identifies a Layer or Group) and an Enable tag (which determines if the Layer or Group should become visible or hidden). |
224 | | |
225 | | When any layer or group changes visibility via the legend control or programmatically via the API, if a LayerEvent exists for that Layer or Group, then the appropriate OnEnable or OnDisable block will be 'executed' as well. This means any layers or groups in the appropriate block will change state as dictated by the Enable tag of that Layer or Group. |
226 | | |
227 | | Example LayerEvents block: |
228 | | |
229 | | <LayerEvents> |
230 | | <Layer> |
231 | | <Name>RoadBuffer</Name> |
232 | | <OnEnable> |
233 | | <Layer> |
234 | | <Name>RoadCenterline</Name> |
235 | | <Enable>true</Enable> |
236 | | </Layer> |
237 | | </OnEnable> |
238 | | <OnDisable> |
239 | | <Layer> |
240 | | <Name>RoadCenterline</Name> |
241 | | <Enable>false</Enable> |
242 | | </Layer> |
243 | | </OnDisable> |
244 | | </Layer> |
245 | | </LayerEvents> |
246 | | Example |
247 | | |
248 | | A complete Map block example: |
249 | | |
250 | | <Map> |
251 | | <ResourceId>Library://Samples/Sheboygan/Maps/Sheboygan.MapDefinition</ResourceId> |
252 | | <Links> |
253 | | <Group> |
254 | | <Name>Transportation</Name> |
255 | | <Url>http://localhost/transportation.html</Url> |
256 | | </Group> |
257 | | <Layer> |
258 | | <Name>Parcels</Name> |
259 | | <Url>http://localhost/parcels.html</Url> |
260 | | </Layer> |
261 | | </Links> |
262 | | <LayerEvents> |
263 | | <Layer> |
264 | | <Name>RoadBuffer</Name> |
265 | | <OnEnable> |
266 | | <Layer> |
267 | | <Name>RoadCenterline</Name> |
268 | | <Enable>true</Enable> |
269 | | </Layer> |
270 | | </OnEnable> |
271 | | <OnDisable> |
272 | | <Layer> |
273 | | <Name>RoadCenterline</Name> |
274 | | <Enable>false</Enable> |
275 | | </Layer> |
276 | | </OnDisable> |
277 | | </Layer> |
278 | | </LayerEvents> |
279 | | </Map> |
280 | | ToolBars |
281 | | |
282 | | ToolBars are provided as a convenience for creating user interface elements that are displayed as a horizontal toolbar of buttons, menus and separators. A Web Layout may specify zero or more ToolBar tags. |
283 | | A ToolBar contains the following sub-tags: |
284 | | Name. Required. This is a unique name for the ToolBar. The ToolBar element that is created has an HTML id with this value. |
285 | | Container. Required. This is the HTML id of an element (typically a DIV) that the ToolBar is to be created within. More than one ToolBar can be assigned to the same container. |
286 | | Visible. Optional. This contains either true or false, indicating the initial visibility of the ToolBar. The default value is true. There is currently no way to change the visibility of a ToolBar so it is recommended to leave this tag out or set it to true. |
287 | | Button. Optional. There can be zero or more Button blocks in a ToolBar, although a ToolBar with no buttons has no purpose. Button blocks are described in more detail below. |
288 | | Button blocks |
289 | | |
290 | | A Button block inside a ToolBar is used to make something appear in the user interface. The order of Buttons in the ToolBar is used to determine the order of the elements in the user interface. A Button block contains a mandatory Function tag which must contain one of the following values: |
291 | | Command. |
292 | | Flyout |
293 | | Separator |
294 | | |
295 | | If the Function tag value is Command, the Button is a clickable button that activates a Command described in the WebLayout. This Button block contains one more tag, Command, which contains the name of a Command to be found in the CommandSet (Commands and the CommandSet are described below. |
296 | | |
297 | | If the Function tag value is Flyout, the Button is specifying a drop-down menu that opens when the user clicks the Button in the ToolBar. This Button block contains a Label tag, which contains the text displayed in the ToolBar, and some number of SubItem tags that specify the items in the menu. The SubItem blocks are structured identically to a Button block, and contain a Function tag and variable other tags depending on the value of the Function tag. Flyout menus can contain sub-menus by specifying a Function tag value of Flyout. |
298 | | |
299 | | If the Function tag value is Separator, the Button specifies a visual separator is to be placed in the ToolBar. Separators have no other tags in their Button block. |
300 | | |
301 | | An example of a ToolBar block is: |
302 | | |
303 | | <ToolBar> |
304 | | <Name>MainToolbar</Name> |
305 | | <Container>ToolbarContainer</Container> |
306 | | <Visible>true</Visible> |
307 | | <Button> |
308 | | <Function>Command</Function> |
309 | | <Command>ZoomIn</Command> |
310 | | </Button> |
311 | | <Button> |
312 | | <Function>Command</Function> |
313 | | <Command>ZoomOut</Command> |
314 | | </Button> |
315 | | <Button> |
316 | | <Function>Flyout</Function> |
317 | | <Label>Extent History</Label> |
318 | | <SubItem> |
319 | | <Function>Command</Function> |
320 | | <Command>PreviousExtent</Command> |
321 | | </SubItem> |
322 | | <SubItem> |
323 | | <Function>Command</Function> |
324 | | <Command>NextExtent</Command> |
325 | | </SubItem> |
326 | | </Button> |
327 | | </ToolBar> |
328 | | |
329 | | CommandSet |
330 | | |
331 | | The CommandSet block is mandatory and only one CommandSet block is allowed in the WebLayout. The CommandSet block contains one or more Command blocks. The Command blocks are used to configure widgets. |
332 | | |
333 | | Although the content of a Command block is dictated by the type of widget that the Command will create, some elements of Command blocks are common. This document describes the common elements. Additional configuration of Commands is described in the Command Reference document. |
334 | | |
335 | | All Command blocks contain the following tags: |
336 | | |
337 | | Name. The Name of the Command is used by Fusion to determine where the Command is to be placed in the user interface. The Command will be created inside an HTML element that has an id with the same value as the Command's Name. In the case of a Command that is referenced by a ToolBar, the Command does not require an HTML element as the ToolBar will create one for the Command. Each Command must have a unique Name. |
338 | | Action. The Action of the Command is the actual widget that will be created for the Command. If a Command references a widget that does not exist, an error will occur that will prevent the application from loading. |
339 | | Location. This is an optional tag and is used to identify where custom widgets can be found. If Location is not provided, the widget is assumed to be one of the stock widgets distributed with Fusion. If the Location is provided, it must be a relative path to the directory containing the widget's javascript file. Fusion has an ext directory and, by convention, custom widgets (and optional packages of widgets) are installed in sub-directories under this directory. If you follow this convention, the Location tag would contain a value like 'ext/mywidgets'. |
340 | | TargetViewer. This tag is provided for backwards compatibility. It is not used by Fusion and is ignored. In future versions, this tag will be removed entirely. It should contain a value of 'All'. |
341 | | |
342 | | Please use the Command Reference document to find out about the specific tags used by the various widgets. |
343 | | Understanding Events |
| 170 | Server Tier: |
| 171 | This tier runs the !MapGuide Open Source server. Fusion is not integrated into this tier. |
| 172 | Web Extensions Tier: |
| 173 | This tier runs with a Web Server. Fusion is installed in this tier and makes use of the !MapGuide Open Source Web Extensions API to implement some functionality. |
| 174 | Client Tier: |
| 175 | This tier runs in the client's web browser. Most of Fusion exists in this tier, and it completely replaces the existing !MapGuide Open Source client tier (known as the AJAX viewer). |
| 176 | |
| 177 | Diagram 1 shows how Fusion integrates into the !MapGuide Open Source Tiers. The blue blocks are new Fusion components and the light grey blocks are existing !MapGuide Open Source components. |
| 178 | |
| 179 | The Fusion Server components work directly with the !MapGuide Open Source PHP API to implement specific functionality such as buffering features and working with selections. |
| 180 | |
| 181 | The Fusion !JavaScript API and widgets are installed with the !MapGuide Open Source Web Tier, but they are actually loaded up to and executed in the Client Tier. |
| 182 | |
| 183 | == !ApplicationDefinitions, HTML and Widgets == |
| 184 | |
| 185 | The API and widgets are linked to specific HTML elements within an HTML page through the !ApplicationDefinition XML document. A widget is the executable code (!JavaScript class) that is loaded when Fusion identifies an HTML element id and Widget Name that are the same. The Type of the Widget identifies the exact !JavaScript file to be loaded and the !JavaScript object that needs to be instantiated to create a functional widget. The runtime instance of the !JavaScript object is the widget. |
| 186 | |
| 187 | When the runtime instance is created, it uses the HTML element id to determine where in the HTML page it should display its user interface. Any custom configuration for the widget is placed in the ApplicationDefinition Widget XML block as sub tags (each widget has its own list of what customization is possible, see the Widget API Reference for details). |
| 188 | |
| 189 | If you are customizing the look and feel of a single widget by overriding the CSS styling for the widget, this is normally done by using the {{{#<id>}}} syntax to limit your changes to that specific widget. |
| 190 | |
| 191 | |
| 192 | == Understanding Events == |