package com.smartgwt.client.docs;


/*
 * Smart GWT (GWT for SmartClient)
 * Copyright 2008 and beyond, Isomorphic Software, Inc.
 *
 * Smart GWT is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License version 3
 * as published by the Free Software Foundation.  Smart GWT is also
 * available under typical commercial license terms - see
 * http://smartclient.com/license
 *
 * This software is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 */
/* sgwtgen */
 
/**
 * A TaskInputExpression is a way to specify a value in the declarative workflow system
 * ({@link com.smartgwt.client.util.workflow.Process} / {@link com.smartgwt.client.util.workflow.Task}) that is derived
 * from the running {@link com.smartgwt.client.util.workflow.Process#getState process state},
 *  the {@link com.smartgwt.client.util.workflow.Task#setOutput output} of a previous task in the process, or from global
 *  context such as {@link com.smartgwt.client.util.workflow.Process#getRuleScope ruleScope}.
 *  <p>
 *  For example, in {@link com.smartgwt.client.util.workflow.FormEditNewRecordTask}, <code>taskInputExpressions</code> are
 * allowed in the {@link com.smartgwt.client.util.workflow.FormEditNewRecordTask#getInitialValues initialValues} specified
 * for
 *  the task, making it very easy to build a process that fetches data from the server
 *  and populates a form with that data.
 *  <p>
 * Similarly, in {@link com.smartgwt.client.util.workflow.GridFetchDataTask}, <code>taskInputExpressions</code> are allowed
 *  in the {@link com.smartgwt.client.util.workflow.GridFetchDataTask#getCriteria criteria} specified for the task, as the
 *  {@link com.smartgwt.client.data.Criterion#getValue Criterion.value} for any criterion.
 *  <p>
 *  <code>TaskInputExpressions</code> are designed to be visual-tool-friendly so that it's
 *  easy to visually wire together processes in the {@link com.smartgwt.client.docs.ReifyAddWorkflowTask Workflow Editor}.
 *  <p>
 *  A TaskInputExpression is a String prefixed with "$input", "$inputRecord", "$ruleScope",
 *  "$state" or "$last" followed by an optional dot-separated hierarchical path,
 *  which can specify either an atomic data value (String, Number) or Record from the
 * input data. For example, if the {@link com.smartgwt.client.util.workflow.Process#getState Process.state} represented in
 * JSON were:
 *  <pre>
 *  {
 *     orderId:5,
 *     orderItems: [
 *        {name:"Pencils", quantity:3, itemId:2344}
 *     ],
 *     orderUser: { name:"Henry Winkle", address:"...", ... }
 *  }
 *  </pre>
 *  .. and a task specified an <code>inputs</code> of "orderId" and an inputFieldList of
 *  "orderItems","orderUser", then:
 *  <ul>
 *  <li>$input is the value 5
 *  <li>$inputRecord.orderUser.name is "Henry Winkle"
 *  <li>$inputRecord.orderItems[0] is the first orderItems Record ({name:"Pencils", ... })
 *  </ul>
 *  <p>
 *  "$ruleScope" can be used to pull values from a {@link com.smartgwt.client.widgets.Canvas#getRuleScope ruleScope}
 * {@link com.smartgwt.client.widgets.Canvas#getRuleContext ruleContext} when configured in {@link
 * com.smartgwt.client.util.workflow.Process#getRuleScope Process.ruleScope}.
 *  <ul>
 *  <li>$ruleScope.property references the ruleContext "property" field
 *  </ul>
 *  <p>
 *  Two others sources of input are "$state" and "$last". The former references the
 *  contents of the {@link com.smartgwt.client.util.workflow.Process#getState Process.state} and the latter the
 *  {@link com.smartgwt.client.util.workflow.Process#getState transient state}.
 *  <ul>
 *  <li>$state is the full contents of the process state
 *  <li>$state.orderId is the "orderId" field of the process state (5 from the example above)
 *  <li>$last is the full output of the previous task executed in the process
 *  <li>$last.property is the "property" field of the previous task executed in the process
 *  <li>$last[service].property or $last[DSRequestTask].property references the last "DSRequestTask"
 *      output in the "property" field
 *  <li>$ruleScope.property references the ruleScope "property" field
 *  </ul>
 *  <p>
 *  The last two sources of input are "$lastRequest" and "$lastResponse". These are the
 *  objects <code>dsRequest</code> and <code>dsResponse</code> representing the last
 * {@link com.smartgwt.client.util.workflow.DSRequestTask}, {@link com.smartgwt.client.util.workflow.DSFetchTask}, {@link
 * com.smartgwt.client.util.workflow.DSAddTask}, {@link com.smartgwt.client.util.workflow.DSUpdateTask} or
 *  {@link com.smartgwt.client.util.workflow.DSRemoveTask} DataSource operation as returned in the operation's
 *  {@link com.smartgwt.client.data.DSCallback callback}. A common usage would be to reference
 *  $lastResponse.totalRows to know how many rows were returned from a fetch.
 *  <p>
 *  <h4>Transient state outputs</h4>
 *  Most tasks pass the output from the <i>previous</i> task as their output (i.e. passed
 *  through) making it easy to refer to earlier output without referencing the task type.
 *  Tasks that work with records or interact with the user, however, typically provide
 *  task-specific output as detailed below:
 *  <ul>
 *  <li><b>DSRequestTask</b>: the contents of dsResponse.data.
 *  <li><b>ScriptTask</b>: the result of {@link com.smartgwt.client.util.workflow.ScriptTask#execute execute()} or,
 *      for an asynchronous task, the value passed to
 *      {@link com.smartgwt.client.util.workflow.ScriptTask#setOutput setOutput()}.
 *  <li><b>StateTask</b>: the value assigned to the outputField.
 *  <li><b>UserTask</b>: the values of the targetForm or targetVM when the task completes.
 *  <li><b>AskForValueTask</b>: an object with "value" and "canceled" properties.
 *  <li><b>FetchRelatedDataTask</b>: the first fetched record.
 *  <li><b>GridFetchDataTask</b>: the contents of dsResponse.data.
 *  <li><b>GridTransferSelectedTask</b>: the first transfered record.
 *  <li><b>GridSelectRecordsTask</b>: on a select, the set of newly selected records,
 *      even if other records are also selected. On a deselect, the entire set of
 *      de-selected records.
 *  <li><b>FetchRelatedDataTask</b>: the first fetched related record.
 *  <li><b>FormSaveDataTask</b>: an object with "valuesValid" and "errors" properties.
 *  <li><b>FormValidateValuesTask</b>: an object with "valuesValid" and "errors" properties.
 *  <li><b>GetPropertiesTask</b>: an object with selected properties and values retrieved.
 *  </ul>
 */
public interface TaskInputExpression  {
}
