@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.) hq.recaptime.dev/wiki/Phorge
phorge phabricator
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

Add a side nav to Conduit API method console pages

Summary: Ref T13072. Make large Conduit doc pages a bit more navigable. This prepares for updating "harbormaster.sendmessage" to support sending messages to builds.

Test Plan: Viewed various Conduit API documentation pages, clicked links.

Subscribers: PHID-OPKG-gm6ozazyms6q6i22gyam

Maniphest Tasks: T13072

Differential Revision: https://secure.phabricator.com/D21696

+298 -114
+3 -3
resources/celerity/map.php
··· 9 9 'names' => array( 10 10 'conpherence.pkg.css' => '0e3cf785', 11 11 'conpherence.pkg.js' => '020aebcf', 12 - 'core.pkg.css' => '0ae696de', 12 + 'core.pkg.css' => '00a2e7f4', 13 13 'core.pkg.js' => 'd2de90d9', 14 14 'dark-console.pkg.js' => '187792c2', 15 15 'differential.pkg.css' => 'ffb69e3d', ··· 171 171 'rsrc/css/phui/phui-invisible-character-view.css' => 'c694c4a4', 172 172 'rsrc/css/phui/phui-left-right.css' => '68513c34', 173 173 'rsrc/css/phui/phui-lightbox.css' => '4ebf22da', 174 - 'rsrc/css/phui/phui-list.css' => '2f253c22', 174 + 'rsrc/css/phui/phui-list.css' => '0c04affd', 175 175 'rsrc/css/phui/phui-object-box.css' => 'b8d7eea0', 176 176 'rsrc/css/phui/phui-pager.css' => 'd022c7ad', 177 177 'rsrc/css/phui/phui-pinboard-view.css' => '1f08f5d8', ··· 872 872 'phui-invisible-character-view-css' => 'c694c4a4', 873 873 'phui-left-right-css' => '68513c34', 874 874 'phui-lightbox-css' => '4ebf22da', 875 - 'phui-list-view-css' => '2f253c22', 875 + 'phui-list-view-css' => '0c04affd', 876 876 'phui-object-box-css' => 'b8d7eea0', 877 877 'phui-oi-big-ui-css' => 'fa74cc35', 878 878 'phui-oi-color-css' => 'b517bfa0',
+2
src/__phutil_library_map__.php
··· 338 338 'ChatLogConduitAPIMethod' => 'applications/chatlog/conduit/ChatLogConduitAPIMethod.php', 339 339 'ChatLogQueryConduitAPIMethod' => 'applications/chatlog/conduit/ChatLogQueryConduitAPIMethod.php', 340 340 'ChatLogRecordConduitAPIMethod' => 'applications/chatlog/conduit/ChatLogRecordConduitAPIMethod.php', 341 + 'ConduitAPIDocumentationPage' => 'applications/conduit/data/ConduitAPIDocumentationPage.php', 341 342 'ConduitAPIMethod' => 'applications/conduit/method/ConduitAPIMethod.php', 342 343 'ConduitAPIMethodTestCase' => 'applications/conduit/method/__tests__/ConduitAPIMethodTestCase.php', 343 344 'ConduitAPIRequest' => 'applications/conduit/protocol/ConduitAPIRequest.php', ··· 6430 6431 'ChatLogConduitAPIMethod' => 'ConduitAPIMethod', 6431 6432 'ChatLogQueryConduitAPIMethod' => 'ChatLogConduitAPIMethod', 6432 6433 'ChatLogRecordConduitAPIMethod' => 'ChatLogConduitAPIMethod', 6434 + 'ConduitAPIDocumentationPage' => 'Phobject', 6433 6435 'ConduitAPIMethod' => array( 6434 6436 'Phobject', 6435 6437 'PhabricatorPolicyInterface',
+96 -7
src/applications/conduit/controller/PhabricatorConduitConsoleController.php
··· 88 88 $crumbs->addTextCrumb($method->getAPIMethodName()); 89 89 $crumbs->setBorder(true); 90 90 91 + $documentation_pages = $method->getDocumentationPages($viewer); 92 + 93 + $documentation_view = $this->newDocumentationView( 94 + $method, 95 + $documentation_pages); 96 + 91 97 $view = id(new PHUITwoColumnView()) 92 98 ->setHeader($header) 93 99 ->setFooter(array( 100 + 101 + id(new PhabricatorAnchorView()) 102 + ->setAnchorName('overview'), 94 103 $info_box, 95 - $method->getMethodDocumentation(), 104 + 105 + id(new PhabricatorAnchorView()) 106 + ->setAnchorName('documentation'), 107 + $documentation_view, 108 + 109 + id(new PhabricatorAnchorView()) 110 + ->setAnchorName('call'), 96 111 $form_box, 112 + 113 + id(new PhabricatorAnchorView()) 114 + ->setAnchorName('examples'), 97 115 $this->renderExampleBox($method, null), 98 116 )); 99 117 100 118 $title = $method->getAPIMethodName(); 101 119 120 + $nav = $this->newNavigationView($method, $documentation_pages); 121 + 102 122 return $this->newPage() 103 123 ->setTitle($title) 104 124 ->setCrumbs($crumbs) 125 + ->setNavigation($nav) 105 126 ->appendChild($view); 106 127 } 107 128 129 + private function newDocumentationView( 130 + ConduitAPIMethod $method, 131 + array $documentation_pages) { 132 + assert_instances_of($documentation_pages, 'ConduitAPIDocumentationPage'); 133 + 134 + $viewer = $this->getViewer(); 135 + 136 + $description_properties = id(new PHUIPropertyListView()); 137 + 138 + $description_properties->addTextContent( 139 + new PHUIRemarkupView($viewer, $method->getMethodDescription())); 140 + 141 + $description_box = id(new PHUIObjectBoxView()) 142 + ->setHeaderText(pht('Method Description')) 143 + ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) 144 + ->appendChild($description_properties); 145 + 146 + $view = array(); 147 + $view[] = $description_box; 148 + 149 + foreach ($documentation_pages as $page) { 150 + $view[] = $page->newView(); 151 + } 152 + 153 + return $view; 154 + } 155 + 156 + private function newNavigationView( 157 + ConduitAPIMethod $method, 158 + array $documentation_pages) { 159 + assert_instances_of($documentation_pages, 'ConduitAPIDocumentationPage'); 160 + 161 + $console_uri = urisprintf( 162 + '/method/%s/', 163 + $method->getAPIMethodName()); 164 + $console_uri = $this->getApplicationURI($console_uri); 165 + $console_uri = new PhutilURI($console_uri); 166 + 167 + $nav = id(new AphrontSideNavFilterView()) 168 + ->setBaseURI($console_uri); 169 + 170 + $nav->selectFilter(null); 171 + 172 + $nav->newLink('overview') 173 + ->setHref('#overview') 174 + ->setName(pht('Overview')) 175 + ->setIcon('fa-list'); 176 + 177 + $nav->newLink('documentation') 178 + ->setHref('#documentation') 179 + ->setName(pht('Documentation')) 180 + ->setIcon('fa-book'); 181 + 182 + foreach ($documentation_pages as $page) { 183 + $nav->newLink($page->getAnchor()) 184 + ->setHref('#'.$page->getAnchor()) 185 + ->setName($page->getName()) 186 + ->setIcon($page->getIconIcon()) 187 + ->setIndented(true); 188 + } 189 + 190 + $nav->newLink('call') 191 + ->setHref('#call') 192 + ->setName(pht('Call Method')) 193 + ->setIcon('fa-play'); 194 + 195 + $nav->newLink('examples') 196 + ->setHref('#examples') 197 + ->setName(pht('Examples')) 198 + ->setIcon('fa-folder-open-o'); 199 + 200 + return $nav; 201 + } 202 + 108 203 private function buildMethodProperties(ConduitAPIMethod $method) { 109 204 $viewer = $this->getViewer(); 110 205 ··· 171 266 pht('Errors'), 172 267 $error_description); 173 268 174 - 175 269 $scope = $method->getRequiredScope(); 176 270 switch ($scope) { 177 271 case ConduitAPIMethod::SCOPE_ALWAYS: ··· 200 294 ' ', 201 295 $oauth_description, 202 296 )); 203 - 204 - $view->addSectionHeader( 205 - pht('Description'), PHUIPropertyListView::ICON_SUMMARY); 206 - $view->addTextContent( 207 - new PHUIRemarkupView($viewer, $method->getMethodDescription())); 208 297 209 298 return $view; 210 299 }
+61
src/applications/conduit/data/ConduitAPIDocumentationPage.php
··· 1 + <?php 2 + 3 + final class ConduitAPIDocumentationPage 4 + extends Phobject { 5 + 6 + private $name; 7 + private $anchor; 8 + private $iconIcon; 9 + private $content = array(); 10 + 11 + public function setName($name) { 12 + $this->name = $name; 13 + return $this; 14 + } 15 + 16 + public function getName() { 17 + return $this->name; 18 + } 19 + 20 + public function setAnchor($anchor) { 21 + $this->anchor = $anchor; 22 + return $this; 23 + } 24 + 25 + public function getAnchor() { 26 + return $this->anchor; 27 + } 28 + 29 + public function setContent($content) { 30 + $this->content = $content; 31 + return $this; 32 + } 33 + 34 + public function getContent() { 35 + return $this->content; 36 + } 37 + 38 + public function setIconIcon($icon_icon) { 39 + $this->iconIcon = $icon_icon; 40 + return $this; 41 + } 42 + 43 + public function getIconIcon() { 44 + return $this->iconIcon; 45 + } 46 + 47 + public function newView() { 48 + $anchor_name = $this->getAnchor(); 49 + $anchor_view = id(new PhabricatorAnchorView()) 50 + ->setAnchorName($anchor_name); 51 + 52 + $content = $this->content; 53 + 54 + return array( 55 + $anchor_view, 56 + $content, 57 + ); 58 + } 59 + 60 + 61 + }
+27 -2
src/applications/conduit/method/ConduitAPIMethod.php
··· 40 40 */ 41 41 abstract public function getMethodDescription(); 42 42 43 - public function getMethodDocumentation() { 44 - return null; 43 + final public function getDocumentationPages(PhabricatorUser $viewer) { 44 + $pages = $this->newDocumentationPages($viewer); 45 + return $pages; 46 + } 47 + 48 + protected function newDocumentationPages(PhabricatorUser $viewer) { 49 + return array(); 50 + } 51 + 52 + final protected function newDocumentationPage(PhabricatorUser $viewer) { 53 + return id(new ConduitAPIDocumentationPage()) 54 + ->setIconIcon('fa-chevron-right'); 55 + } 56 + 57 + final protected function newDocumentationBoxPage( 58 + PhabricatorUser $viewer, 59 + $title, 60 + $content) { 61 + 62 + $box_view = id(new PHUIObjectBoxView()) 63 + ->setHeaderText($title) 64 + ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) 65 + ->setTable($content); 66 + 67 + return $this->newDocumentationPage($viewer) 68 + ->setName($title) 69 + ->setContent($box_view); 45 70 } 46 71 47 72 abstract protected function defineParamTypes();
-8
src/applications/harbormaster/conduit/HarbormasterConduitAPIMethod.php
··· 7 7 'PhabricatorHarbormasterApplication'); 8 8 } 9 9 10 - public function getMethodStatus() { 11 - return self::METHOD_STATUS_UNSTABLE; 12 - } 13 - 14 - public function getMethodStatusDescription() { 15 - return pht('All Harbormaster APIs are new and subject to change.'); 16 - } 17 - 18 10 protected function returnArtifactList(array $artifacts) { 19 11 $list = array(); 20 12
+74 -51
src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php
··· 60 60 PhabricatorEnv::getDoclink('Conduit API: Using Search Endpoints')); 61 61 } 62 62 63 - final public function getMethodDocumentation() { 63 + final protected function newDocumentationPages(PhabricatorUser $viewer) { 64 64 $viewer = $this->getViewer(); 65 65 66 66 $engine = $this->newSearchEngine() ··· 70 70 71 71 $out = array(); 72 72 73 - $out[] = $this->buildQueriesBox($engine); 74 - $out[] = $this->buildConstraintsBox($engine); 75 - $out[] = $this->buildOrderBox($engine, $query); 76 - $out[] = $this->buildFieldsBox($engine); 77 - $out[] = $this->buildAttachmentsBox($engine); 78 - $out[] = $this->buildPagingBox($engine); 73 + $out[] = $this->buildQueriesDocumentationPage($viewer, $engine); 74 + $out[] = $this->buildConstraintsDocumentationPage($viewer, $engine); 75 + $out[] = $this->buildOrderDocumentationPage($viewer, $engine, $query); 76 + $out[] = $this->buildFieldsDocumentationPage($viewer, $engine); 77 + $out[] = $this->buildAttachmentsDocumentationPage($viewer, $engine); 78 + $out[] = $this->buildPagingDocumentationPage($viewer, $engine); 79 79 80 80 return $out; 81 81 } 82 82 83 - private function buildQueriesBox( 83 + private function buildQueriesDocumentationPage( 84 + PhabricatorUser $viewer, 84 85 PhabricatorApplicationSearchEngine $engine) { 85 86 $viewer = $this->getViewer(); 86 87 ··· 140 141 null, 141 142 )); 142 143 143 - return id(new PHUIObjectBoxView()) 144 - ->setHeaderText(pht('Builtin and Saved Queries')) 145 - ->setCollapsed(true) 146 - ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) 147 - ->appendChild($this->newRemarkupDocumentationView($info)) 148 - ->appendChild($table); 144 + $title = pht('Prebuilt Queries'); 145 + $content = array( 146 + $this->newRemarkupDocumentationView($info), 147 + $table, 148 + ); 149 + 150 + return $this->newDocumentationBoxPage($viewer, $title, $content) 151 + ->setAnchor('queries'); 149 152 } 150 153 151 - private function buildConstraintsBox( 154 + private function buildConstraintsDocumentationPage( 155 + PhabricatorUser $viewer, 152 156 PhabricatorApplicationSearchEngine $engine) { 153 157 154 158 $info = pht(<<<EOTEXT ··· 281 285 'wide', 282 286 )); 283 287 284 - return id(new PHUIObjectBoxView()) 285 - ->setHeaderText(pht('Custom Query Constraints')) 286 - ->setCollapsed(true) 287 - ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) 288 - ->appendChild($this->newRemarkupDocumentationView($info)) 289 - ->appendChild($table) 290 - ->appendChild($constant_lists); 288 + 289 + $title = pht('Constraints'); 290 + $content = array( 291 + $this->newRemarkupDocumentationView($info), 292 + $table, 293 + $constant_lists, 294 + ); 295 + 296 + return $this->newDocumentationBoxPage($viewer, $title, $content) 297 + ->setAnchor('constraints') 298 + ->setIconIcon('fa-filter'); 291 299 } 292 300 293 - private function buildOrderBox( 301 + private function buildOrderDocumentationPage( 302 + PhabricatorUser $viewer, 294 303 PhabricatorApplicationSearchEngine $engine, 295 304 $query) { 296 305 ··· 388 397 'wide', 389 398 )); 390 399 400 + $title = pht('Result Ordering'); 401 + $content = array( 402 + $this->newRemarkupDocumentationView($orders_info), 403 + $orders_table, 404 + $this->newRemarkupDocumentationView($columns_info), 405 + $columns_table, 406 + ); 391 407 392 - return id(new PHUIObjectBoxView()) 393 - ->setHeaderText(pht('Result Ordering')) 394 - ->setCollapsed(true) 395 - ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) 396 - ->appendChild($this->newRemarkupDocumentationView($orders_info)) 397 - ->appendChild($orders_table) 398 - ->appendChild($this->newRemarkupDocumentationView($columns_info)) 399 - ->appendChild($columns_table); 408 + return $this->newDocumentationBoxPage($viewer, $title, $content) 409 + ->setAnchor('ordering') 410 + ->setIconIcon('fa-sort-numeric-asc'); 400 411 } 401 412 402 - private function buildFieldsBox( 413 + private function buildFieldsDocumentationPage( 414 + PhabricatorUser $viewer, 403 415 PhabricatorApplicationSearchEngine $engine) { 404 416 405 417 $info = pht(<<<EOTEXT ··· 470 482 'wide', 471 483 )); 472 484 473 - return id(new PHUIObjectBoxView()) 474 - ->setHeaderText(pht('Object Fields')) 475 - ->setCollapsed(true) 476 - ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) 477 - ->appendChild($this->newRemarkupDocumentationView($info)) 478 - ->appendChild($table); 485 + $title = pht('Object Fields'); 486 + $content = array( 487 + $this->newRemarkupDocumentationView($info), 488 + $table, 489 + ); 490 + 491 + return $this->newDocumentationBoxPage($viewer, $title, $content) 492 + ->setAnchor('fields') 493 + ->setIconIcon('fa-cube'); 479 494 } 480 495 481 - private function buildAttachmentsBox( 496 + private function buildAttachmentsDocumentationPage( 497 + PhabricatorUser $viewer, 482 498 PhabricatorApplicationSearchEngine $engine) { 483 499 484 500 $info = pht(<<<EOTEXT ··· 560 576 'wide', 561 577 )); 562 578 563 - return id(new PHUIObjectBoxView()) 564 - ->setHeaderText(pht('Attachments')) 565 - ->setCollapsed(true) 566 - ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) 567 - ->appendChild($this->newRemarkupDocumentationView($info)) 568 - ->appendChild($table); 579 + $title = pht('Attachments'); 580 + $content = array( 581 + $this->newRemarkupDocumentationView($info), 582 + $table, 583 + ); 584 + 585 + return $this->newDocumentationBoxPage($viewer, $title, $content) 586 + ->setAnchor('attachments') 587 + ->setIconIcon('fa-cubes'); 569 588 } 570 589 571 - private function buildPagingBox( 590 + private function buildPagingDocumentationPage( 591 + PhabricatorUser $viewer, 572 592 PhabricatorApplicationSearchEngine $engine) { 573 593 574 594 $info = pht(<<<EOTEXT ··· 631 651 EOTEXT 632 652 ); 633 653 634 - return id(new PHUIObjectBoxView()) 635 - ->setHeaderText(pht('Paging and Limits')) 636 - ->setCollapsed(true) 637 - ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) 638 - ->appendChild($this->newRemarkupDocumentationView($info)); 654 + $title = pht('Paging and Limits'); 655 + $content = array( 656 + $this->newRemarkupDocumentationView($info), 657 + ); 658 + 659 + return $this->newDocumentationBoxPage($viewer, $title, $content) 660 + ->setAnchor('paging') 661 + ->setIconIcon('fa-clone'); 639 662 } 640 663 641 664 }
+5 -6
src/applications/transactions/conduit/TransactionSearchConduitAPIMethod.php
··· 13 13 'or an entire object type.'); 14 14 } 15 15 16 - public function getMethodDocumentation() { 16 + protected function newDocumentationPages(PhabricatorUser $viewer) { 17 17 $markup = pht(<<<EOREMARKUP 18 18 When an object (like a task) is edited, Phabricator creates a "transaction" 19 19 and applies it. This list of transactions on each object is the basis for ··· 77 77 78 78 $markup = $this->newRemarkupDocumentationView($markup); 79 79 80 - return id(new PHUIObjectBoxView()) 81 - ->setCollapsed(true) 82 - ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) 83 - ->setHeaderText(pht('Method Details')) 84 - ->appendChild($markup); 80 + return array( 81 + $this->newDocumentationBoxPage($viewer, pht('Method Details'), $markup) 82 + ->setAnchor('details'), 83 + ); 85 84 } 86 85 87 86 protected function defineParamTypes() {
+23 -21
src/applications/transactions/editengine/PhabricatorEditEngineAPIMethod.php
··· 38 38 PhabricatorEnv::getDoclink('Conduit API: Using Edit Endpoints')); 39 39 } 40 40 41 - final public function getMethodDocumentation() { 42 - $viewer = $this->getViewer(); 43 - 41 + final protected function newDocumentationPages(PhabricatorUser $viewer) { 44 42 $engine = $this->newEditEngine() 45 43 ->setViewer($viewer); 46 44 ··· 48 46 49 47 $out = array(); 50 48 51 - $out[] = $this->buildEditTypesBoxes($engine, $types); 52 - 53 - return $out; 49 + return $this->buildEditTypesDocumentationPages($viewer, $engine, $types); 54 50 } 55 51 56 - private function buildEditTypesBoxes( 52 + private function buildEditTypesDocumentationPages( 53 + PhabricatorUser $viewer, 57 54 PhabricatorEditEngine $engine, 58 55 array $types) { 59 56 60 - $boxes = array(); 57 + $pages = array(); 61 58 62 59 $summary_info = pht( 63 60 'This endpoint supports these types of transactions. See below for '. ··· 83 80 'wide', 84 81 )); 85 82 86 - $boxes[] = id(new PHUIObjectBoxView()) 87 - ->setHeaderText(pht('Transaction Types')) 88 - ->setCollapsed(true) 89 - ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) 90 - ->appendChild($this->buildRemarkup($summary_info)) 91 - ->appendChild($summary_table); 83 + $title = pht('Transaction Summary'); 84 + $content = array( 85 + $this->buildRemarkup($summary_info), 86 + $summary_table, 87 + ); 88 + 89 + $pages[] = $this->newDocumentationBoxPage($viewer, $title, $content) 90 + ->setAnchor('types'); 92 91 93 92 foreach ($types as $type) { 94 93 $section = array(); ··· 130 129 'wide', 131 130 )); 132 131 133 - $boxes[] = id(new PHUIObjectBoxView()) 134 - ->setHeaderText(pht('Transaction Type: %s', $type->getEditType())) 135 - ->setCollapsed(true) 136 - ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) 137 - ->appendChild($this->buildRemarkup($section)) 138 - ->appendChild($type_table); 132 + $title = $type->getEditType(); 133 + $content = array( 134 + $this->buildRemarkup($section), 135 + $type_table, 136 + ); 137 + 138 + $pages[] = $this->newDocumentationBoxPage($viewer, $title, $content) 139 + ->setAnchor($type->getEditType()) 140 + ->setIconIcon('fa-pencil'); 139 141 } 140 142 141 - return $boxes; 143 + return $pages; 142 144 } 143 145 144 146
+5 -13
src/infrastructure/edges/conduit/EdgeSearchConduitAPIMethod.php
··· 11 11 return pht('Read edge relationships between objects.'); 12 12 } 13 13 14 - public function getMethodDocumentation() { 15 - $viewer = $this->getViewer(); 16 - 14 + protected function newDocumentationPages(PhabricatorUser $viewer) { 17 15 $rows = array(); 18 16 foreach ($this->getConduitEdgeTypeMap() as $key => $type) { 19 17 $inverse_constant = $type->getInverseEdgeConstant(); ··· 48 46 'wide', 49 47 )); 50 48 51 - return id(new PHUIObjectBoxView()) 52 - ->setHeaderText(pht('Edge Types')) 53 - ->setTable($types_table); 54 - } 55 49 56 - public function getMethodStatus() { 57 - return self::METHOD_STATUS_UNSTABLE; 58 - } 59 - 60 - public function getMethodStatusDescription() { 61 - return pht('This method is new and experimental.'); 50 + return array( 51 + $this->newDocumentationBoxPage($viewer, pht('Edge Types'), $types_table) 52 + ->setAnchor('types'), 53 + ); 62 54 } 63 55 64 56 protected function defineParamTypes() {
+2 -3
webroot/rsrc/css/phui/phui-list.css
··· 75 75 padding: 4px 10px; 76 76 } 77 77 78 - .phui-list-sidenav .phui-list-item-has-icon .phui-list-item-indented { 79 - padding-left: 18px; 78 + .phabricator-side-menu .phui-list-item-has-icon .phui-list-item-indented { 79 + padding-left: 24px; 80 80 } 81 - 82 81 83 82 .device-desktop .phui-list-sidenav .phui-list-item-href:hover { 84 83 background: {$sky};