mirror of
https://we.phorge.it/source/phorge.git
synced 2024-11-26 16:52:41 +01:00
Expand documentation for "transaction.search"
Summary: Depends on D20209. Ref T13255. It would probably be nice to make this into a "real" `*.search` API method some day, but at least document the features for now. Test Plan: Read documentation. Reviewers: amckinley Reviewed By: amckinley Maniphest Tasks: T13255 Differential Revision: https://secure.phabricator.com/D20211
This commit is contained in:
parent
83aba7b01c
commit
d1546209c5
3 changed files with 72 additions and 28 deletions
|
@ -409,4 +409,19 @@ abstract class ConduitAPIMethod
|
||||||
$capability);
|
$capability);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
final protected function newRemarkupDocumentationView($remarkup) {
|
||||||
|
$viewer = $this->getViewer();
|
||||||
|
|
||||||
|
$view = new PHUIRemarkupView($viewer, $remarkup);
|
||||||
|
|
||||||
|
$view->setRemarkupOptions(
|
||||||
|
array(
|
||||||
|
PHUIRemarkupView::OPTION_PRESERVE_LINEBREAKS => false,
|
||||||
|
));
|
||||||
|
|
||||||
|
return id(new PHUIBoxView())
|
||||||
|
->appendChild($view)
|
||||||
|
->addPadding(PHUI::PADDING_LARGE);
|
||||||
|
}
|
||||||
|
|
||||||
}
|
}
|
||||||
|
|
|
@ -144,7 +144,7 @@ EOTEXT
|
||||||
->setHeaderText(pht('Builtin and Saved Queries'))
|
->setHeaderText(pht('Builtin and Saved Queries'))
|
||||||
->setCollapsed(true)
|
->setCollapsed(true)
|
||||||
->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
|
->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
|
||||||
->appendChild($this->buildRemarkup($info))
|
->appendChild($this->newRemarkupDocumentationView($info))
|
||||||
->appendChild($table);
|
->appendChild($table);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -223,7 +223,7 @@ EOTEXT
|
||||||
);
|
);
|
||||||
|
|
||||||
if ($constants) {
|
if ($constants) {
|
||||||
$constant_lists[] = $this->buildRemarkup(
|
$constant_lists[] = $this->newRemarkupDocumentationView(
|
||||||
pht(
|
pht(
|
||||||
'Constants supported by the `%s` constraint:',
|
'Constants supported by the `%s` constraint:',
|
||||||
'statuses'));
|
'statuses'));
|
||||||
|
@ -283,7 +283,7 @@ EOTEXT
|
||||||
->setHeaderText(pht('Custom Query Constraints'))
|
->setHeaderText(pht('Custom Query Constraints'))
|
||||||
->setCollapsed(true)
|
->setCollapsed(true)
|
||||||
->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
|
->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
|
||||||
->appendChild($this->buildRemarkup($info))
|
->appendChild($this->newRemarkupDocumentationView($info))
|
||||||
->appendChild($table)
|
->appendChild($table)
|
||||||
->appendChild($constant_lists);
|
->appendChild($constant_lists);
|
||||||
}
|
}
|
||||||
|
@ -391,9 +391,9 @@ EOTEXT
|
||||||
->setHeaderText(pht('Result Ordering'))
|
->setHeaderText(pht('Result Ordering'))
|
||||||
->setCollapsed(true)
|
->setCollapsed(true)
|
||||||
->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
|
->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
|
||||||
->appendChild($this->buildRemarkup($orders_info))
|
->appendChild($this->newRemarkupDocumentationView($orders_info))
|
||||||
->appendChild($orders_table)
|
->appendChild($orders_table)
|
||||||
->appendChild($this->buildRemarkup($columns_info))
|
->appendChild($this->newRemarkupDocumentationView($columns_info))
|
||||||
->appendChild($columns_table);
|
->appendChild($columns_table);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -472,7 +472,7 @@ EOTEXT
|
||||||
->setHeaderText(pht('Object Fields'))
|
->setHeaderText(pht('Object Fields'))
|
||||||
->setCollapsed(true)
|
->setCollapsed(true)
|
||||||
->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
|
->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
|
||||||
->appendChild($this->buildRemarkup($info))
|
->appendChild($this->newRemarkupDocumentationView($info))
|
||||||
->appendChild($table);
|
->appendChild($table);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -562,7 +562,7 @@ EOTEXT
|
||||||
->setHeaderText(pht('Attachments'))
|
->setHeaderText(pht('Attachments'))
|
||||||
->setCollapsed(true)
|
->setCollapsed(true)
|
||||||
->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
|
->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
|
||||||
->appendChild($this->buildRemarkup($info))
|
->appendChild($this->newRemarkupDocumentationView($info))
|
||||||
->appendChild($table);
|
->appendChild($table);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -633,21 +633,7 @@ EOTEXT
|
||||||
->setHeaderText(pht('Paging and Limits'))
|
->setHeaderText(pht('Paging and Limits'))
|
||||||
->setCollapsed(true)
|
->setCollapsed(true)
|
||||||
->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
|
->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
|
||||||
->appendChild($this->buildRemarkup($info));
|
->appendChild($this->newRemarkupDocumentationView($info));
|
||||||
}
|
}
|
||||||
|
|
||||||
private function buildRemarkup($remarkup) {
|
|
||||||
$viewer = $this->getViewer();
|
|
||||||
|
|
||||||
$view = new PHUIRemarkupView($viewer, $remarkup);
|
|
||||||
|
|
||||||
$view->setRemarkupOptions(
|
|
||||||
array(
|
|
||||||
PHUIRemarkupView::OPTION_PRESERVE_LINEBREAKS => false,
|
|
||||||
));
|
|
||||||
|
|
||||||
return id(new PHUIBoxView())
|
|
||||||
->appendChild($view)
|
|
||||||
->addPadding(PHUI::PADDING_LARGE);
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
|
|
|
@ -8,15 +8,58 @@ final class TransactionSearchConduitAPIMethod
|
||||||
}
|
}
|
||||||
|
|
||||||
public function getMethodDescription() {
|
public function getMethodDescription() {
|
||||||
return pht('Read transactions for an object.');
|
return pht('Read transactions and comments for an object.');
|
||||||
}
|
}
|
||||||
|
|
||||||
public function getMethodStatus() {
|
public function getMethodDocumentation() {
|
||||||
return self::METHOD_STATUS_UNSTABLE;
|
$markup = pht(<<<EOREMARKUP
|
||||||
}
|
When an object (like a task) is edited, Phabricator creates a "transaction"
|
||||||
|
and applies it. This list of transactions on each object is the basis for
|
||||||
|
essentially all edits and comments in Phabricator. Reviewing the transaction
|
||||||
|
record allows you to see who edited an object, when, and how their edit changed
|
||||||
|
things.
|
||||||
|
|
||||||
public function getMethodStatusDescription() {
|
One common reason to call this method is that you're implmenting a webhook and
|
||||||
return pht('This method is new and experimental.');
|
just received a notification that an object has changed. See the Webhooks
|
||||||
|
documentation for more detailed discussion of this use case.
|
||||||
|
|
||||||
|
Constraints
|
||||||
|
===========
|
||||||
|
|
||||||
|
These constraints are supported:
|
||||||
|
|
||||||
|
- `phids` //Optional list<phid>.// Find specific transactions by PHID. This
|
||||||
|
is most likely to be useful if you're responding to a webhook notification
|
||||||
|
and want to inspect only the related events.
|
||||||
|
- `authorPHIDs` //Optional list<phid>.// Find transactions with particular
|
||||||
|
authors.
|
||||||
|
|
||||||
|
Transaction Format
|
||||||
|
==================
|
||||||
|
|
||||||
|
Each transaction has custom data describing what the transaction did. The
|
||||||
|
format varies from transaction to transaction. The easiest way to figure out
|
||||||
|
exactly what a particular transaction looks like is to make the associated kind
|
||||||
|
of edit to a test object, then query that object.
|
||||||
|
|
||||||
|
Not all transactions have data: by default, transactions have a `null` "type"
|
||||||
|
and no additional data. This API does not expose raw transaction data because
|
||||||
|
some of it is internal, oddly named, misspelled, confusing, not useful, or
|
||||||
|
could create security or policy problems to expose directly.
|
||||||
|
|
||||||
|
New transactions are exposed (with correctly spelled, comprehensible types and
|
||||||
|
useful, reasonable fields) as we become aware of use cases for them.
|
||||||
|
|
||||||
|
EOREMARKUP
|
||||||
|
);
|
||||||
|
|
||||||
|
$markup = $this->newRemarkupDocumentationView($markup);
|
||||||
|
|
||||||
|
return id(new PHUIObjectBoxView())
|
||||||
|
->setCollapsed(true)
|
||||||
|
->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
|
||||||
|
->setHeaderText(pht('Method Details'))
|
||||||
|
->appendChild($markup);
|
||||||
}
|
}
|
||||||
|
|
||||||
protected function defineParamTypes() {
|
protected function defineParamTypes() {
|
||||||
|
|
Loading…
Reference in a new issue