The configurator has the choice to use the built-in editor (e.g. from the web user interface) OR editing XML files directly using any XML editing tool.

• The built-in editor:

  • The editor "knows" the entire structure of the XML files.

    • Which elements may be used. The user interface lists element types in a dropdown.

    • Which elements may be "nested" inside which elements. The user interface only allows creating a new element of type X below a parent element of type Y, if type Y may have type X as a "child" element.

    • Which attributes/properties may be set on each element type. Depending on the type of the selected element, different tabs with fields for attributes are displayed.

    • Which are the legal values for each attribute/property. The user interface for an attributes depends on type of attribute value (boolean attributes display as checkboxes, enumerations as dropdowns, etc.).

    For this reason, the editor is the recommended tool for configurators (with the possible exception of expert users who know exactly what they are doing).

  • The editor has a checkout/checkin mechanism. This prevents multiple configurators from editing a given file simultaneously.

  • Because the editor is part of the web user interface, it works on files (form templates and structure files) residing on the web server. It is NOT necessary to have access to the file system of the web server (by file shares or remote desktop tools).

• Standard XML editing tools.

  • The form templates and the the structure file are XML files, and are thus editable by any standard tool, that allows editing of XML files. This includes "plain text editors" like Notepad and XML-savvy editors like the one in Visual Studio.

  • XML editing is far easier in XML-savvy editors like the one in Visual Studio compared to using "plain text editors" like Notepad. An XML-savvy editor assists the user in getting all the < and > characters right, closing every element, indenting, etc. So using the XML editor of Visual Studio (or a similar XML editor) is highly recommended over using "plain text editors" like Notepad.

    Note
    There is no schema that defines the structure of form templates and the the structure file. As a consequence, the Visual Studio XML editor does not "know" the legal elements and attribute names, and hence it cannot validate the XML files being edited - and "Intellisense" does not work.

  • Using these standard XML editing tools requires access to the file system of the webserver. This is seldom a problem, however - because the normal (and recommended) scenario is like this:

    • Create/edit/test configuration files like form templates and the the structure file in a local environment (the configurator's PC, or a server in the current comain - using file shares).

    • When a an intended level of functionality has been developed, deploy the configuration to a (remote) web server that hosts customer's test or production environment.

    Caution

    When using a standard XML editing tool and subsequently deploying / uploading modifed files, the TOPICA "check out / check in" system is NOT respected. I.e. there is no check to prevent for simultaneous modification by other users using the TOPICAeditor. To ensure that this does not cause problems, always use one environment as "master" (typically the development environment), and all others (for example test / production environments) should be "slave".

  • Using these standard XML editing tools is obviously less safe than using the editor - so why use these standard XML editing tools?

    • If the configurator knows exactly what (s)he is doing (konws the elements, attributes and legal value of each attribute), using standard XML editing tools are faster to work with.

    • It is easier to get an overview of an entire form templates / the structure file, because all elements and attributes are displayed in one window.

      For this reason it is easier to search for the use of specific attribute or attribute values, and move/copy elements around (within one file, or across files) - these tasks are much harder to perform in the editor.

It is not a choice of either/or. It is perfectly possible to switch back and forth between using the editor and standard XML editing tools. You just need to be aware of a few details:

Note
There are some characters, that cannot be written directly in XML attributes - they must be encoded. The editor handles this encoding automatically - when using standard XML editing tools, the configurator must "manually" encode the following characters:

Note
Any "white space" and XML comments added in a standard XML editing tool (e.g. to enhance readablity) will be REMOVED, when a file is saved in the editor

Note
Any line breaks added in a standard XML editing tool (e.g. to enhance readablity in long strings of JavaScript, SQL, or TOPICA Basic) will be REPLACED with XML-escaped characters).

<TableView Caption="Child subtables:" SQLQuery="
    SELECT 
        TableName, Caption 
    FROM 
        DataDictionaryTable t
        JOIN DataDictionaryRelation r ON
            (r.ParentTableName='{Table.Name}') AND (r.ChildTableName=t.TableName)
" />

<TableView Caption="Child subtables:" SQLQuery="&#xD;&#xA;                    SELECT &#xD;&#xA;                        TableName, Caption &#xD;&#xA;                    FROM &#xD;&#xA;                        DataDictionaryTable t&#xD;&#xA;                        JOIN DataDictionaryRelation r ON&#xD;&#xA;                            (r.ParentTableName='{Table.Name}') AND (r.ChildTableName=t.TableName)&#xD;&#xA;                " ConnectString="" Header="true" />