define([
'viewmodel/js/api/Archetype'
], function(
Archetype) {
'use strict';
/**
* {@link viewmodel/js/api/Archetype Archetype} representing a single record
* for a businness object.
*
* As it mostly covers use-cases related to work with a form it also provides
* operations related to the bound Business Object, for example
* {@link viewmodel/js/api/DetailArchetype#save save one record} or
* {@link viewmodel/js/api/DetailArchetype#getRecord get viewed record}.
*
* @AbcsAPI stable
* @version 16.3.5
* @exports viewmodel/js/api/DetailArchetype
* @constructor
* @private
* @augments viewmodel/js/api/Archetype
* @param {entity/js/api/Entity} entity
* @param {Object} descriptor JSON archetype descriptor
*/
var DetailArchetype = function (entity, descriptor) {
AbcsLib.checkThis(this);
Archetype.call(this, entity, descriptor);
};
AbcsLib.extend(DetailArchetype, Archetype);
/**
* Returns current record represented by this archetype instance. The returned
* object can be used to alter current record data.
*
* You will need to get the record for the most of {@link module:api/js/Pages Navigation API}
* methods when passing data between pages, see an example below.
*
* @AbcsAPI stable
* @version 16.3.5
* @returns {viewmodel/js/api/Record} object holding current data
* @example <caption>Get the current record and pass it to the edit customer page</caption>
* var customerToEdit = ContextualData.createRecordToEditContext({
* // what business object are these data of:
* entityId: 'customer',
* // pass the currently viewed customer record
* data: customerDetailArchetype.getRecord()
* });
* // navigate to the customer edit page
* Abcs.Pages().navigateToPage('customerEditPage', customerToEdit);
*/
DetailArchetype.prototype.getRecord = function () {};
/**
* Save the given record, that is create or update a record according to its
* state.
*
* The state is determined by the way the archetype's owning page was opened
* and what {@link viewmodel/js/api/context/ContextualData ContextualData}
* passed to the page through the {@link module:api/js/Pages Navigation API}.
* If e.g. {@link viewmodel/js/api/context/ContextualData.createRecordToEditContext ContextualData.createRecordToEditContext}
* is used to create the data passed to the page, the archetype will be in
* the <i>edit mode</i>. On the other hand {@link viewmodel/js/api/context/ContextualData.createStartWithBlankRecordContext ContextualData.createStartWithBlankRecordContext}
* determines the <i>create mode</i>.
*
* The method merely saves the passed record and stays on the same page. If
* you wish to pass the saved record forward to another page (such as move to
* a detail page after saving the record) you will need to use the {@link module:api/js/Pages Navigation API}
* manually to do so.
*
* @AbcsAPI stable
* @version 16.3.5
* @param {viewmodel/js/api/Record} record to save
* @returns {Promise} promise resolved to saved {@link viewmodel/js/api/Record record}
* instance when the save successfully finishes and rejected in case of an error.
* @example <caption>Modify the current record and save the changes</caption>
* // get the current live archetype's instance of a Record
* var customerRecord = customerEditArchetype.getRecord();
*
* // get number of orders the customer has made so far
* var numberOfOrders = customerRecord.getValue('numberOfOrders');
*
* // check if number of orders is more than five and promote the customer
* // to a Premium state
* if (numberOfOrders > 5) {
* customerRecord.setValue('state', 'Premium');
*
* // save the modifications
* customerEditArchetype.save(customerRecord).then(function () {
* console.log('Successfully saved.');
* });
* }
*/
DetailArchetype.prototype.save = function(/*record*/) {};
/**
* Register hooks into the DetailArchetype notifying about load and save
* operations.
*
* @param {Object} handlerRegistration { loadHandler: function(Record), saveHandler: function(Record), beforeSaveHandler: function(Record) }
*/
DetailArchetype.prototype.registerHandlers = function (/*handlerRegistration*/) {};
/**
* Unregister hooks from the DetailArchetype
* operations.
*
* @see {@link module:viewmodel/js/api/DetailArchetype.registerHandlers}
* @param {Object} handlerRegistration { loadHandler: function(), saveHandler: function() }
*/
DetailArchetype.prototype.unregisterHandlers = function (/*handlerRegistration*/) {};
/**
* Returns an object that contains a set of fields and observables you can
* bind to in your components and use to communicate with other components on
* a page bound to the same fields.
*
* @AbcsAPI stable
* @version 16.3.5
* @returns {viewmodel/js/api/DetailArchetype~DetailObservables} observables exposed by the archetype
* @function
*/
DetailArchetype.prototype.getObservables = Archetype.prototype.getObservables;
/**
* Contains set of fields and observables you can bind to in your components
* and use to communicate with other components on a page bound to the same
* fields.
*
* Besides the published observables you may use archetype's methods to
* interact with it.
*
* @AbcsAPI stable
* @typedef viewmodel/js/api/DetailArchetype~DetailObservables
* @property {Object<String, ko.observable>} record map of {@link http://knockoutjs.com/documentation/observables.html ko observables}
* wrapping values of all fields of the Business Object the archetype is bound to.
* Unlike {@link DetailArchetype.getRecord DetailArchetype.getRecord}
* this allows you to bind your HTML view directly to the field value and
* read or modify it immediately via {@link http://knockoutjs.com/documentation/introduction.html ko binding}.
* See the example below.
* @property {Object<String, ko.observable>} item <em>Deprecated</em>, use DetailObservables.record instead.
* Map of {@link http://knockoutjs.com/documentation/observables.html ko observables}
*
* @version 16.3.5
* @example <caption>Bind to the customer's last name directly from an HTML
* element with ko binding</caption>
* <label for="customerLastName">Customer last name</label>
* <input id="customerLastName" data-bind="value: $root.Observables.customerFormArchetype.record.lastName"></input>
*
* @example <caption>Use the observables in custom code and listen for changes
* in a REFERENCE type field value.</caption>
* // subscribe to the ko observable to catch its value changes
* var record = pageModel.Observables.customerFormArchetype.record;
* var subscription = record.refToCustomer.subscribe(function (newCustomerId) {
* console.log('New Customer ID value is: ' + newCustomerId);
* // do something here related to your model
* });
* ...
* // do not forget to dispose the listener when no longer needed.
* subscription.dispose();
*
*/
return DetailArchetype;
});