Document object

 

 

Base prototype for all Document objects

Syntax

To create a Document object:

var parameters = new Document.Parameters ( );
parameters.left.url = "c:\\temp\\plouf"
parameters.right.url = "c:\\temp\\plouf2"
parameters.gui_type = "diff2";
parameters.document_type = "folders";

var doc = new Document (parameters, "view")

Parameters

document_parameters.  Documents.Parameters object. Describes all the sources of data, the mode of comparison and the various settings to use

activity. Document Activity string. Purpose of the document. In combination with the options, it helps to determine exactly which type of comparison is appropriate given the sources of data

Property Of

none.

Implemented In

ECMerge 2.1

Description

The Document object is ECMerge object.

It is the central object of ECMerge, it realizes the comparison operation, load and saves data. It lets you study the comparison results.

Properties

Property	Description
information	Object. Read-Only. Information deduced from run-time settings, comparison or files. Contains one member per side (indexed by Side string).
parameters	Document.Parameters object.  Read-Only. Current parameters for the document

Properties of information[side]

Property	Description
file_type	For files only, else undefined. UserFileType or ConfigurationObject object. Indicates which file type is used to interpret the content of that file

 

NB: there may be additional information for specific document type, such TextDocument.

 

Methods

load

get_statistics
is_in_fully_solved_state
reload
do_import
do_export
set_parameters
synchronize_options

Examples

Example 1.

Creates a document and displays it with focus.

var parameters = new Document.Parameters();
parameters.left.url = "c:\\temp\\plouf"
parameters.right.url = "c:\\temp\\plouf2"

var doc = new Document (parameters);

add_view (doc, true);

See also

Documents.Parameters object, Document Activity string

Method load

Syntax

function load (url)
returns a Document derived object

Parameters

url. URL object or String. Location of the ECMS or ECMT file.

Method Of

Document constructor

Implemented In

ECMerge 2.1

Description

Loads an ECMS or ECMT file from a given location, creates the appropriate type of Document for it and returns this document.

Examples

Example 1.

Loads a document from a file with a local path, using automatic upgrade from String to URL:

var my_doc = Document.load ("/loca/path/website-sync.ecmt");

Method get_statistics

Syntax

function Document.get_statistics ( )
function FolderDocument.get_statistics (selection)
returns a Statistics object

Parameters

selection. FolderDocument.Select. Specifies the sub-set of folder items for which the statistics are computed.

Method Of

Document object, FolderDocument object

Implemented In

ECMerge 2.1

Description

Computes the statistics for the document or sub-set of it, and returns a Statistics object describing the result.

Examples

see Statistics object examples.

See Also

Document object, FolderDocument object, Statistics object

 

Method is_in_fully_solved_state

Syntax

function Document.is_in_fully_solved_state( )
returns a boolean

Parameters

 none.

Method Of

none.

Implemented In

ECMerge 2.1.75

Description

Returns true when the document is fully solved. This is the case all the data are neither in conflict nor un-written (for folders). Basically, after a merge operation, it means that everything is OK.

Examples

Example 1.

This simple tells whether the document currently viewed is in fully solved state: 

var my_doc = current_frame.coordinator.document;
alert (my_doc.is_in_fully_solved_state() ? "totally solved" : "some conflicts are there or things remain to be written");

See Also 

  Document object, FolderDocument object

Method reload

Syntax

function Document.reload (smart, side)

Parameters

smart. Boolean. True to get a reload only if specified side changed. False if reload is systematic. If omitted, true is implied
side. Side String or undefined. Side of the comparison to reload. If undefined or omitted, all the sides used in the comparison or viewer are/is reloaded.

Method Of

Document object

Implemented In

ECMerge 2.1

Description

Reloads the given side in a smart or systematic way. Once the data is reloaded, comparison computations are re-done if necessary.

Examples

Example 1.

Reloads forcefully the right side of a document:

var my_doc;
my_doc.reload (false, "right");

See Also

Document object

Methods do_export / do_import

Syntax

function Document.do_export (format, need_new_name, questions_answers)
function Document.do_import (format, need_new_name, questions_answers)

Parameters

format. Document Format string. One of the supported document format. For import, only "unix_patch" is supported currently.
need_new_name. Boolean or undefined. True if you want the UI to be displayed, false if you do not want the UI to be displayed. If undefined or omitted, Ellié Computing Merge takes the decision whether a UI should be displayed.
questions_answers. Questions/Answers string. Gives pre-established answers to known UI questions, allowing you to avoid messages boxes.

Method Of

Document object

Implemented In

ECMerge 2.1

Description

do_export saves information in the requested format, following the settings and locations specified in the current Document.parameters.
do_import imports information, following the same logic.

The Document.Parameters object contains an OptionsSet member called 'settings' which in turn contains under 'export' namespace many options which are used during the import or export operation.

NB: a 4th parameter may be later added, which would specify the actual sub-set of options or an OptionsSet distinct from Document.parameters.settings, making the call more practical.

Examples

Example 1.

Loads a document from a file with a local path, then exports an XML reports for it at specified location:

var report_target_location = "/tmp/test.xml";
var doc = Document.load ("/loca/path/website-sync.ecmt");

var doc_parameters = doc.parameters.clone ();
doc_parameters.settings["export.xml_export.to.location"].url = report_target_location;
doc_parameters.settings["export.xml_export.embed_file_reports"] = true;
doc_parameters.settings["export.xml_export.sub_reports_format"] = "xml";
log (doc_parameters.settings);
doc.parameters = doc_parameters;
 
// generate the XML report
try {
    doc.do_export ("xml", false);
}
catch (err) {
     log (err);
}

See Also

Document object, Document.Parameters object, OptionsSet object, Questions/Answers string

Method set_parameters

Syntax

function Document.set_parameters (new_parameters, from_application)

 

Parameters

new_parameters.  Document.Parameters object. New parameters which should replace current document parameters
from_application. Boolean. If true, only options not specific to that document are concerned (i.e. excluding export locations, comparison file name)

Method Of

Document object

Implemented In

ECMerge 2.4

Description

This function is used to change parameters of the document once it is created. It allows the caller to change input urls, numbers of sources as well as all the comparison and view options. It cannot be used to change the type of document though.

Examples

Example 1.

This example demonstrates how to change the kind of patch to generate for the document currently viewed in ECMerge:

var doc = current_frame.coordinator.document;
var parameters = doc.parameters.clone();
parameters.settings["export.unixpatch_export.output_format.format"] = "unix-patch-unified";
parameters.settings["export.unixpatch_export.output_format.context_lines"] = "5";
doc.set_parameters (parameters); 

See Also

  Document.Parameters object

Method synchronize_options

Syntax

function Document.synchronize_options ( replace )
 

Parameters

replace. Boolean. If not specified or undefined, the question Keep/Replace is asked if necessary. If specified, True accepts application options changes and False provoques the Keep semantic

Method Of

Document object

Implemented In

ECMerge 2.2

Description

Call this function to ask for the synchronization between the application master copy of an OptionsSet and the one saved in the document. This function is internally called each time a document gets viewed.

Examples

Example 1.

Loads a document from a file with a local path, using automatic upgrade from String to URL, then force it to get the options from the application master copy:

var my_doc = Document.load ("/loca/path/website-sync.ecmt");
my_doc.synchronize_options (true);

See Also 

"The reference copy of options set '<name>' changed..." message, OptionsSet object