mirror of
https://we.phorge.it/source/phorge.git
synced 2024-11-10 17:02: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);
|
||||
}
|
||||
|
||||
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'))
|
||||
->setCollapsed(true)
|
||||
->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
|
||||
->appendChild($this->buildRemarkup($info))
|
||||
->appendChild($this->newRemarkupDocumentationView($info))
|
||||
->appendChild($table);
|
||||
}
|
||||
|
||||
|
@ -223,7 +223,7 @@ EOTEXT
|
|||
);
|
||||
|
||||
if ($constants) {
|
||||
$constant_lists[] = $this->buildRemarkup(
|
||||
$constant_lists[] = $this->newRemarkupDocumentationView(
|
||||
pht(
|
||||
'Constants supported by the `%s` constraint:',
|
||||
'statuses'));
|
||||
|
@ -283,7 +283,7 @@ EOTEXT
|
|||
->setHeaderText(pht('Custom Query Constraints'))
|
||||
->setCollapsed(true)
|
||||
->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
|
||||
->appendChild($this->buildRemarkup($info))
|
||||
->appendChild($this->newRemarkupDocumentationView($info))
|
||||
->appendChild($table)
|
||||
->appendChild($constant_lists);
|
||||
}
|
||||
|
@ -391,9 +391,9 @@ EOTEXT
|
|||
->setHeaderText(pht('Result Ordering'))
|
||||
->setCollapsed(true)
|
||||
->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
|
||||
->appendChild($this->buildRemarkup($orders_info))
|
||||
->appendChild($this->newRemarkupDocumentationView($orders_info))
|
||||
->appendChild($orders_table)
|
||||
->appendChild($this->buildRemarkup($columns_info))
|
||||
->appendChild($this->newRemarkupDocumentationView($columns_info))
|
||||
->appendChild($columns_table);
|
||||
}
|
||||
|
||||
|
@ -472,7 +472,7 @@ EOTEXT
|
|||
->setHeaderText(pht('Object Fields'))
|
||||
->setCollapsed(true)
|
||||
->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
|
||||
->appendChild($this->buildRemarkup($info))
|
||||
->appendChild($this->newRemarkupDocumentationView($info))
|
||||
->appendChild($table);
|
||||
}
|
||||
|
||||
|
@ -562,7 +562,7 @@ EOTEXT
|
|||
->setHeaderText(pht('Attachments'))
|
||||
->setCollapsed(true)
|
||||
->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
|
||||
->appendChild($this->buildRemarkup($info))
|
||||
->appendChild($this->newRemarkupDocumentationView($info))
|
||||
->appendChild($table);
|
||||
}
|
||||
|
||||
|
@ -633,21 +633,7 @@ EOTEXT
|
|||
->setHeaderText(pht('Paging and Limits'))
|
||||
->setCollapsed(true)
|
||||
->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() {
|
||||
return pht('Read transactions for an object.');
|
||||
return pht('Read transactions and comments for an object.');
|
||||
}
|
||||
|
||||
public function getMethodStatus() {
|
||||
return self::METHOD_STATUS_UNSTABLE;
|
||||
}
|
||||
public function getMethodDocumentation() {
|
||||
$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() {
|
||||
return pht('This method is new and experimental.');
|
||||
One common reason to call this method is that you're implmenting a webhook and
|
||||
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() {
|
||||
|
|
Loading…
Reference in a new issue