API reference¶
Visualizer¶
init¶
init() needs to be called only once while your application initializes itself. For example, in AngularJS app it can be called in app.module.ts while in React it can be called before ReactDom.render(..);
load¶
load() needs to be called only whenever a new instance of <two-dc-layout> web component is added to the DOM. It call basically loads all the twodc's internal components into the new new instance of <two-dc-layout>
onLoad¶
This method is used to add a callback that needs to be called every time new data loads into twodc.
import {setDataString, onLoad} from '@siemens-ag/twodc-redlining';
const data = `{ reportDrawing: {...}, ... }`; // twodc compatible json datastring
onLoad('layoutName', () => { window.alert('new data loaded inside twodc')})
setDataString('layoutName', data);
onDestroy¶
This method is used to add a callback that needs to be called every time the twodc-layout is destroyed or deleted.
import {setDataString, onDestroy} from '@siemens-ag/twodc-redlining';
onDestroy('layoutName', () => { window.alert('twodc-layout is deleted')})
dispose¶
Just like init method, dispose is also a lifecycle hook that needs to be called when twodc needs to be disposed. This method cleans up the DOM elements created by or related to twodc and the memory utilized by it. Usually, this needs to be called within the onDestroy lifecycle hook of the component in which twodc is rendered.
Typically in AngularJS inside $onDestroy(), in Angular2+ inside ngOnDestroy and in ReactJS inside componentWillUnmount() methods
import {dispose} from '@siemens-ag/twodc-redlining';
dispose('layoutName');
deleteContent¶
deleteContent method can be called to clear the rendered content inside twodc. This api can be used if you need to clear the data rendered and optionally load new data via setDataString or setDataURL methods.
import {setDataURL, deleteContent} from '@siemens-ag/twodc-redlining';
setDataURL('layoutName', 'https:// json-data', 'json')
.then(() => {
console.log('json loaded from url');
deleteContent('layoutOne').then(() => {
console.log('twodc content deleted');
});
});
deleteLayout¶
deleteLayout method needs to be called whenever you need to destroy instance of <two-dc-layout> web component.
import {setDataURL, deleteContent} from '@siemens-ag/twodc-redlining';
setDataURL('layoutName', 'https:// json-data', 'json')
.then(() => {
console.log('json loaded from url');
deleteLayout('layoutName').then(() => {
console.log('twdoc layout web-component deleted')
});
});
Note: In order to load new content inside twodc, it is not necessary to call deleteContent or deleteLayout. You can directly assign new content via setDataString or setDataURL.
recreateLayout¶
When twodc is either disposed or deleteLayout is called, recreateLayout method needs to be called to recreate the destroyed instance of <two-dc-layout> web component.
setDataString¶
setDataString method is used to assign a serialized twodc compatible json data to twodc.
import {setDataString} from '@siemens-ag/twodc-redlining';
// twodc compatible json datastring
const data = `{ reportDrawing: {...}, ... }`;
setDataString('layoutName', data).then(() => console.log('twodc loaded'));
addDataString¶
Similar to addDataString accept renders the new data string over the existing rendered data.
setDataURL¶
setDataURL method is used to assign data that is available on some URL. This URL can point to a JSON, pdf, image, or video. usage: setDataURL('layoutName', '*url', 'json' | 'pdf' | 'image' | 'video')*
import {setDataURL} from '@siemens-ag/twodc-redlining';
// json
setDataURL('layoutName', 'https:// json-data', 'json')
.then(() => {
console.log('json loaded from url');
});
// pdf
setDataURL('layoutName', 'https:// pdf-data', 'pdf')
.then(() => {
console.log('pdf loaded from url');
});
// image
setDataURL('layoutName', 'https:// image-data', 'image')
.then(() => {
console.log('image loaded from url');
});
// video
setDataURL('layoutName', 'https:// video-data', 'image')
.then(() => {
console.log('video loaded from url');
});
Another use-case of setDataURL is to load the data which is in the form of a blob. For example:
import {setDataURL} from '@siemens-ag/twodc-redlining';
// for demo purpose lets create a blob of pdf coming from server
fetch('https:// pdf-data')
.then((response) => response.arrayBuffer())
.then((buf) => {
const blob = new Blob([buf], { type: 'application/pdf' });
// we need to generate a URL representing this blob object
const url = URL.createObjectURL(blob);
// this blob url can now be passed to setDataURL method
setDataURL('layoutOne', url, 'pdf');
});
setPDFFile¶
In case we need to render a pdf from file system via a file picker, we can directly assign the browser File object to this method.
import {setPDFFile} from '@siemens-ag/twodc-redlining';
const input = document.createElement('input');
input.type = 'file';
input.accept = '.pdf';
input.onchange = (event) => {
const file = event.target.files[0];
setPDFFile('layoutName', file);
}
setImageFile¶
Similar to setPDFFile but for image files.
setVideoFile¶
Similar to setPDFFile but for video files.
searchElements¶
If the source data is twodc JSON, objects can be searched and highlighted using searchElements This method with search the rendered object by objectid and once found, will zoom in and highlight it.
import {setDataString, searchElements} from '@siemens-ag/twodc-redlining';
const data = `{ reportDrawing: {...}, ... }`; // twodc compatible json datastring
setDataString('layoutName', data)
.then(() => {
console.log('twodc loaded');
const objectid = `1234546`;
searchElements('layoutName', objectid);
});
searchByLID¶
If the source data is twodc JSON, objects can be searched and highlighted using searchByLID. This method searches the rendered object by lid and once found, will zoom in and highlight it.
import {setDataString, searchByLID} from '@siemens-ag/twodc-redlining';
const data = `{ reportDrawing: {...}, ... }`; // twodc compatible json datastring
setDataString('layoutName', data)
.then(() => {
console.log('twodc loaded');
const lid = `1234546`;
searchByLID('layoutName', lid);
});
searchInPDF¶
This method can be used to programmatically search and highlight text inside a pdf.
`twodcRedlining.searchInPDF('layoutName', '*search_text*');`
clearSearchInPDF¶
Method to clear searched results programmatically
twodcRedlininng.clearSearchInPDF('layoutName');
selectElements¶
selectElements method can be used to programmatically select one or more objects/elements by objectid from the rendered json.
import {setDataString, searchElements} from '@siemens-ag/twodc-redlining';
const data = `{ reportDrawing: {...}, ... }`; // twodc compatible json datastring
setDataString('layoutName', data)
.then(() => {
console.log('twodc loaded');
selectElements('layoutName', ['A3BQHKD7AR','A3BQHKDDAR','A3BQHKOXAR','A3BQHKP4AR']);
});
selectElementsByLID¶
This is similar to selectElements accept, this method is used to search elements by their lid;
deselectAll¶
deselectAll method can be used to programmatically deselect all the selected elements inside twodc.
import {deselectAll} from '@siemens-ag/twodc-redlining';
deselectAll('layoutName');
onSelect¶
This method is used to add a callback that needs to be called whenever an object is selected.
//javascript usage
twodcRedlining.onSelect('layoutName', (args) => {
const element = args[0];
console.log(`object with lid:${element.lid} and objectid:${element.objectid} selected`);
})
onDeselectAll¶
Similar to onSelect accept callback will be triggered on deselecting elements
multiSelectActivate¶
Method to activate/deactivate multiselect
twodcRedlining.multiSelectActivate('layoutName', true/false);
singleSelectActivate¶
Method to activate/deactivate single selection
twodcRedlining.singleSelectActivate('layoutName', true/false)
enableMultiSelection¶
Method to activate/deactivate multiselection and activate/deactivate the UI presence of multiselection toggle button
twodcVisualizer.enableMultiSelection('layoutName', true/false, true/false);
selectIntersectingObjectsActivate¶
Method to activateshowInPeekview/deactivate intersecting objects selection and activate/deactivate the UI presence of select intersecting objects toggle button
twodcVisualizer.selectIntersectingObjectsActivate('layoutName', true/false, true/false);
zoomElements¶
If the source data is twodc JSON, objects can also be zoomed using zoomOnElements This method with search the rendered objects by objectid and once found, will zoom on it.
import {setDataString, zoomElements} from '@siemens-ag/twodc-redlining';
const data = `{ reportDrawing: {...}, ... }`; // twodc compatible json datastring
setDataString('layoutName', data)
.then(() => {
console.log('twodc loaded');
zoomElements('layoutName', ['A3BQHOI3AR','A3BQHOI5AR','A3BQHOI7AR','A3BQHOGSAR']);
});
zoomToQuadrant¶
This method can be used to zoom to a quadrant inside a P&ID rendered in twodc provided quadrant data is available in JSON;
import {setDataString, zoomToQuadrant} from '@siemens-ag/twodc-redlining';
const data = `{ reportDrawing: {...}, ... }`; // twodc compatible json datastring
setDataString('layoutName', data)
.then(() => {
console.log('twodc loaded');
zoomToQuadrant('layoutName', 'B,5');
});
decreaseZoom¶
Method to zoom out programmatically
twodcRedlining.decreaseZoom('layoutName');
increaseZoom¶
Method to zoom in programmatically
twodcRedlining.increaseZoom('layoutName');
resetZoom¶
Method to reset zoom in programmatically
twodcRedlining.resetZoom('layoutName');
setZoom¶
Method to set the zoom level in percentage.
twodcRedlining.setZoom('layoutName', '200');
getZoom¶
Method to set the zoom level in percentage.
const currentZoom = twodcRedlining.getZoom('layoutName');
keepUniformZoom¶
Method to enable/disable uniform zoom across a multi page JSON/pdf rendered in twodc.
twodcRedlining.keepUniformZoom('layoutOne', true/false);`
hideToggleByID¶
If the source data is twodc JSON, objects can be searched and hid using hideToggleByID. This method searches the rendered object by lid and once found, hides it if the boolean parameter is passed as false.
import {setDataString, hideToggleByID} from '@siemens-ag/twodc-redlining';
const data = `{ reportDrawing: {...}, ... }`; // twodc compatible json datastring
setDataString('layoutName', data)
.then(() => {
console.log('twodc loaded');
const lid = `1234546`;
const hide = 0;
hideToggleByID(lid,hide);
});
toggleRuler¶
Method to activate/deactivate ruler
twodcRedlining.toggleRuler('layoutName', true/false);
toggleQuadrant¶
Method to activate/deactivate quadrant ruler
twodcRedlining.toggleQuadrant('layoutName', true/false);
toggleGrid¶
Method to activate/deactivate quadrant grid
twodcRedlining.toggleGrid('layoutName', true/false);
print¶
Method to print content inside twodc
twodcRedlining.print('layoutName');
exportPDF¶
Method to export the current document rendered in twodc as pdf
twodcVisualizer.exportPDf('layoutName');
changeLanguage¶
Method to change localization inside twodc
twodcRedlining.changeLanguage('layoutName', 'en'|'de'|'cn');
peekview¶
Method to get the instance of peekview component of twodc.
const peekview = twodcRedlining.peekview('layoutName');
showInPeekview¶
Method to render a twodc JSON inside peekview.
const jsonString = '{... twodc_Data_json ...}}';
const linkdata = {
object: "A4F8R86XIY",
position: "136, 48",
quadrant: "3,B",
report: "A4F8R7N6IY",
type: "21"
}
twodcRedlining.showInPeekview('layoutName', jsonString, linkdata);`
onPeekviewSplit¶
This method is used to add a callback that needs to be called every time split option is selected in peekview control
twodcRedlining.onPeekviewSplit('layoutName', () => console.log('split option selected'));
onPeekviewSwitch¶
This method is used to add a callback that needs to be called every time switch option is selected in peekview control
twodcRedlining.onPeekviewSwitch('layoutName', () => console.log('split option selected'));
startLoader¶
Method to show the loader
twodcRedlining.showLoader('layoutName');
stopLoader¶
Method to hide the loader
twodcRedlining.showLoader('layoutName');
setColor¶
If the source data is twodc JSON, objects can be searched and given the desired color using setColor. This method searches the rendered object by lid and once found, colors it with the color that is passed in second parameter.
import {setDataString, setColor} from '@siemens-ag/twodc-redlining';
const data = `{ reportDrawing: {...}, ... }`; // twodc compatible json datastring
setDataString('layoutName', data)
.then(() => {
console.log('twodc loaded');
const lid = `1234546`;
const color = `green`;
setColor(lid,color);
});
Redlining¶
Markup¶
In twodc markups drawn are stored in the form of plain javascript objects that can be easily serialized and deserialized. Refer below to the markup and its associated interfaces:
interface TwodcMarkup {
commentData: TwodcMarkupComments;
createdBy: string;
creationDate: string;
documentId: string;
id: string;
pageNo: number;
elementIDs: string[];
drawings: TwodcMarkupDrawing[];
state: MarkupState;
type: string;
status?: MarkupStatus;
}
interface TwodcMarkupComments {
id: string;
subject: string | undefined;
elementIDs: string[];
comments: Record<string,{
createdBy: string;
creationDate: string;
id: string;
sessionId: string;
commentString: string;
};
}
interface TwodcMarkupDrawing {
id: string;
createdBy: string;
creationDate: string;
markupType: string;
gMarkerProperties: IMarkupProperties;
}
A sample markup object might look like
{
"id": "7c5cb6a9-624c-c021-659a-7021c3f07001",
"createdBy": "Tony Stark",
"creationDate": "2021-06-30T10:02:31.703Z",
"commentData": {
"id": "1eeeb646-ac10-0226-5be3-f418aa31ad86",
"subject": "page 3 text ",
"comments": {
"cmt-7852639b-1fd0-a0a2-66cf-c900e2fc6dad": {
"createdBy": "Steve Rogers",
"creationDate": "2021-06-30T10:01:49.014Z",
"id": "cmt-7852639b-1fd0-a0a2-66cf-c900e2fc6dad",
"commentString": "comment 1",
"sessionId": "layoutOne"
},
"cmt-689d0cdb-24b6-772e-6805-521c0eebc5f8": {
"createdBy": "Stephen strange",
"creationDate": "2021-06-30T10:01:50.278Z",
"id": "cmt-689d0cdb-24b6-772e-6805-521c0eebc5f8",
"commentString": "comment 2",
"sessionId": "layoutOne"
}
}
},
"documentId": "blank_layout",
"pageNo": 3,
"elementIDs": [],
"drawings": [{
"id": "text-markup-for-testing",
"createdBy": "IronMan",
"creationDate": "2021-06-30T10:02:31.703Z",
"markupType": "TextMarkup",
"gMarkerProperties": {
"strokeWidth": "1",
"opacity": "1",
"fill": "#FF0000",
"cloudStyle": false,
"type": "Text",
"attributes": {
"centerPoint": {"x": 0,"y": 0},
"displayText": "Sample Text",
"fontSize": "12",
"transform": {
"position": {"x": 440.9, "y": 496.5},
"angle": 0,
"anchorPoint": {"x": 440.9,"y": 496.5}
}
}
}
}],
"state": "SAVED",
"status": "UNRESOLVED"
"type": "TextMarkup"
}
Redlining package comes with a bunch of APIs for working with these markups.
setUserName¶
Method to set a username in twodc. This username will be used to assign markups created inside twodc.
twodcRedlining.setUserName('layoutName', 'Tony Stark');
getUserName¶
Method to get username set in twodc.
const username = twodcRedlining.getUserName('layoutName');
addCollaboratingUsers¶
Method to add collaborating users in twodc
const users = [
{
"id": "1",
"name": "User5",
"isOnline": true,
"imageSrc": "image link"
}]
twodcRedlining.addCollaboratingUsers('layoutOne', users);
addMarkups¶
Method to add/load markups in twodc.
const markups = [{
"id": "97d2371e-423c-4d78-7955-060df8e9bb49",
"createdBy": "Tony Stark",
...
}, {
"id": "7c5cb6a9-624c-c021-659a-7021c3f07001",
"createdBy": "Stephen strange",
...
}];
twodcRedlining.addMarkups('layoutName', markups);
getAllMarkups¶
Method to get all markups. This method returns an array of all the markups in twodc.
const markups = twodcRedlining.getAllMarkups('layoutName');
getMarkupsFromPage¶
Method to get all markups from a page. This method returns an array of markups in twodc a particular page of multi page JSON/pdf.
const secondPageMarkups = twodcRedlining.getMarkupsFromPage('layoutName', 2);
getNewMarkups¶
Method to get an array of all the newly created markups
const newMarkups = twodcRedlining.getNewMarkups('layoutName');`
getUpdatedMarkups¶
Method to get an array of all the updated markups
const updatedMarkups = twodcRedlining.getUpdatedMarkups('layoutName');
saveMarkups¶
Once a markup is created/updated its state is "NEW"/"UPDATED". A markup needs to be marked as "SAVED" before it is exported. This method can be used to save these markups.
twodcRedlining.saveMarkups('layoutName');
onLoadMarkupBtnClick¶
Redlining package has a comment explorer menu where markups and their respective comments can be viewed. Comment explorer has a load markup button that has to be configured with the markup data source.
twodcRedlining.onLoadMarkupBtnClick('layoutName', () => {
//example code
fetch('http://markups-get-url')
.then((res) => res.json())
.then((json) => twodcRedlining.addMarkups('layoutName', json));
});
onSaveMarkupBtnClick¶
Comment explorer also has a save button which when clicked saves the markups. This method can be used to add a callback to the save markup button click event.
twodcRedlining.onSaveMarkupBtnClick('layoutOne',(args) => {
const savedMarkups = args[0];
console.log('markups saved:', savedMarkups);
});
onMarkupUpdate¶
This method can be used to add a callback that triggers whenever a markup drawing, comments, state or status is updated.
twodcRedlining.onAddMarkupComment('layoutOne',(args) => {
const updatedMarkup = args[0];
console.log('markup updated:', updatedMarkup);
});
onAddMarkupComment¶
This method can be used to add a callback that triggers whenever a comment is added to a markup
twodcRedlining.onAddMarkupComment('layoutOne',(args) => {
const updatedMarkup = args[0];
console.log('comment added to markup:', updateMarkup);
});
setMarkupStatusList¶
Method to set or update markup status list in twodc
const markupStatusList = {"initialState":"INCOMPLETE","states":{"INCOMPLETE":{"nextState":["COMPLETED","DEFERRED"],"localization":{"en":"INCOMPLETE","de":"UNVOLLSTÄNDIG"},"disabled":true},"COMPLETED":{"nextState":[],"localization":{"en":"COMPLETED","de":"VOLLENDET"}},"DEFERRED":{"nextState":["INCOMPLETE"],"localization":{"en":"DEFERRED","de":"VERSCHIEBEN"}}}}
twodcRedlining.setMarkupStatusList('layoutOne', markupStatusList);
setMarkupsEditableState¶
Method to set editable state (READONLY, EDITABLE, READONLYWITHCOMMENT) of markups
twodcRedlining.setMarkupsEditableState('layoutOne', 'markupID', 'READONLY');
setDefaultMarkupColor¶
Method to set default color of markups to be drawn in twodc
twodcRedlining.setDefaultMarkupColor('layoutName', '#ff3860');
deleteMarkup¶
This method can be used to programmatically delete a markup by id in twodc
const markupid = '7c5cb6a9-624c-c021-659a-7021c3f07001';
twodcRedlining.deleteMarkup('layoutOne',markupid ,(args) => {
const deletedMarkup = args[0];
console.log('markup deleted:', deletedMarkup);
});
deleteAllMarkups¶
This method can be used to delete all the markups in twodc
twodcRedlining.deleteAllMarkup('layoutOne',markupid ,(args) => {
const deletedMarkups = args[0];
console.log('markups deleted', deletedMarkup);
});
getDeletedMarkups¶
This method can be used to get all the deleted markups
const deletedMarkup = twodcRedlining.getDeletedMarkups('layoutName');
getMode¶
Method to get current mode of twodc
const mode = twodcRedlining.getMode();
SwitchMode¶
Method to switch modes in twodc
const mode = twodcRedlining.SwitchMode();
hideSwitchModeButton¶
Method to hide/show switch mode button present at top-right in twodc
twodcRedlining.hideSwitchModeButton('layoutName', true/false);
readOnlyModeActivate¶
Method to activate/deactivate readonlymode in twodc
twodcRedlining.readOnlyModeActivate('layoutOne', true/false);
| API | Visualizer | Redlining |
|---|---|---|
| init | ✅ | ✅ |
| load | ✅ | ✅ |
| onLoad | ✅ | ✅ |
| onDestroy | ✅ | ✅ |
| dispose | ✅ | ✅ |
| deleteContent | ✅ | ✅ |
| deleteLayout | ✅ | ✅ |
| recreateLayout | ✅ | ✅ |
| setDataString | ✅ | ✅ |
| addDataString | ✅ | ✅ |
| setDataURL | ✅ | ✅ |
| setPDFFile | ✅ | ✅ |
| setImageFile | ✅ | ✅ |
| setVideoFile | ✅ | ✅ |
| searchElements | ✅ | ✅ |
| searchByLID | ✅ | ✅ |
| searchInPDF | ✅ | ✅ |
| clearSearchInPDF | ✅ | ✅ |
| selectElements | ✅ | ✅ |
| selectElementsByLID | ✅ | ✅ |
| deselectAll | ✅ | ✅ |
| onSelect | ✅ | ✅ |
| onDeselectAll | ✅ | ✅ |
| multiSelectActivate | ✅ | ✅ |
| singleSelectActivate | ✅ | ✅ |
| enableMultiSelection | ✅ | ✅ |
| selectIntersectingObjectsActivate | ✅ | ✅ |
| zoomElements | ✅ | ✅ |
| zoomToQuadrant | ✅ | ✅ |
| decreaseZoom | ✅ | ✅ |
| increaseZoom | ✅ | ✅ |
| resetZoom | ✅ | ✅ |
| setZoom | ✅ | ✅ |
| getZoom | ✅ | ✅ |
| keepUniformZoom | ✅ | ✅ |
| hideToggleByID | ✅ | ✅ |
| toggleRuler | ✅ | ✅ |
| toggleQuadrant | ✅ | ✅ |
| toggleGrid | ✅ | ✅ |
| ✅ | ✅ | |
| exportPDF | ✅ | ✅ |
| changeLanguage | ✅ | ✅ |
| peekview | ✅ | ✅ |
| showInPeekview | ✅ | ✅ |
| onPeekviewSplit | ✅ | ✅ |
| onPeekviewSwitch | ✅ | ✅ |
| startLoader | ✅ | ✅ |
| stopLoader | ✅ | ✅ |
| setColor | ✅ | ✅ |
| setUserName | ✅ | |
| getUserName | ✅ | |
| addCollaboratingUsers | ✅ | |
| addMarkups | ✅ | |
| getAllMarkups | ✅ | |
| getMarkupsFromPage | ✅ | |
| getNewMarkups | ✅ | |
| getUpdatedMarkups | ✅ | |
| saveMarkups | ✅ | |
| onLoadMarkupBtnClick | ✅ | |
| onSaveMarkupBtnClick | ✅ | |
| onMarkupUpdate | ✅ | |
| onAddMarkupComment | ✅ | |
| setMarkupsEditableState | ✅ | |
| setMarkupStatusList | ✅ | |
| setDefaultMarkupColor | ✅ | |
| deleteMarkup | ✅ | |
| deleteAllMarkups | ✅ | |
| getDeletedMarkups | ✅ | |
| getMode | ✅ | |
| SwitchMode | ✅ | |
| hideSwitchModeButton | ✅ | |
| readOnlyModeActivate | ✅ |
Community
Connect and Collaborate with Industrial Professionals and Join the Community!