Commit aef6568a authored by colemanw's avatar colemanw

Merge pull request #5090 from colemanw/explorer

Add Examples to api explorer
parents 23fe7478 c28e1768
<?php
/*
+--------------------------------------------------------------------+
| CiviCRM version 4.6 |
+--------------------------------------------------------------------+
| Copyright CiviCRM LLC (c) 2004-2014 |
+--------------------------------------------------------------------+
| This file is a part of CiviCRM. |
| |
| CiviCRM is free software; you can copy, modify, and distribute it |
| under the terms of the GNU Affero General Public License |
| Version 3, 19 November 2007 and the CiviCRM Licensing Exception. |
| |
| CiviCRM 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 Affero General Public License for more details. |
| |
| You should have received a copy of the GNU Affero General Public |
| License and the CiviCRM Licensing Exception along |
| with this program; if not, contact CiviCRM LLC |
| at info[AT]civicrm[DOT]org. If you have questions about the |
| GNU Affero General Public License or the licensing of CiviCRM, |
| see the CiviCRM license FAQ at http://civicrm.org/licensing |
+--------------------------------------------------------------------+
*/
/**
*
* @package CRM
* @copyright CiviCRM LLC (c) 2004-2014
* $Id$
*
*/
/**
* Page for displaying list of contact Subtypes
*/
class CRM_Admin_Page_APIDoc extends CRM_Core_Page {
/**
* @return string
*/
public function run() {
CRM_Utils_System::setTitle(ts('API Parameters'));
return parent::run();
}
/**
* @return string
*/
public function getTemplateFileName() {
return 'CRM/Core/APIDoc.tpl';
}
/**
* Get user context.
*
* @param null $mode
*
* @return string
* user context.
*/
public function userContext($mode = NULL) {
return 'civicrm/api/doc';
}
}
......@@ -42,12 +42,23 @@ class CRM_Admin_Page_APIExplorer extends CRM_Core_Page {
* @return string
*/
public function run() {
CRM_Utils_System::setTitle(ts('API explorer and generator'));
CRM_Core_Resources::singleton()
->addScriptFile('civicrm', 'templates/CRM/Admin/Page/APIExplorer.js')
->addScriptUrl('//cdnjs.cloudflare.com/ajax/libs/prettify/r298/prettify.min.js', 99)
->addStyleUrl('//cdnjs.cloudflare.com/ajax/libs/prettify/r298/prettify.min.css', 99);
$this->assign('operators', CRM_Core_DAO::acceptedSQLOperators());
// List example directories
global $civicrm_root;
$examples = array();
foreach (scandir($civicrm_root . 'api/v3/examples') as $item) {
if ($item && strpos($item, '.') === FALSE) {
$examples[] = $item;
}
}
$this->assign('examples', $examples);
return parent::run();
}
......@@ -61,4 +72,148 @@ class CRM_Admin_Page_APIExplorer extends CRM_Core_Page {
return 'civicrm/api/explorer';
}
/**
* AJAX callback to fetch examples
*/
public static function getExampleFile() {
global $civicrm_root;
if (!empty($_GET['entity']) && strpos($_GET['entity'], '.') === FALSE) {
$examples = array();
foreach (scandir($civicrm_root . 'api/v3/examples/' . $_GET['entity']) as $item) {
$item = str_replace('.php', '', $item);
if ($item && strpos($item, '.') === FALSE) {
$examples[] = array('key' => $item, 'value' => $item);
}
}
CRM_Utils_JSON::output($examples);
}
if (!empty($_GET['file']) && strpos($_GET['file'], '.') === FALSE) {
$fileName = $civicrm_root . 'api/v3/examples/' . $_GET['file'] . '.php';
if (file_exists($fileName)) {
echo file_get_contents($fileName);
}
else {
echo "Not found.";
}
CRM_Utils_System::civiExit();
}
CRM_Utils_System::permissionDenied();
}
/**
* Ajax callback to display code docs
*/
public static function getDoc() {
if (!empty($_GET['entity']) && strpos($_GET['entity'], '.') === FALSE) {
$entity = _civicrm_api_get_camel_name($_GET['entity']);
$action = CRM_Utils_Array::value('action', $_GET);
$doc = self::getDocblock($entity, $action);
$result = array(
'doc' => $doc ? self::formatDocBlock($doc[0]) : 'Not found.',
'code' => $doc ? $doc[1] : NULL,
'file' => $doc ? $doc[2] : NULL,
);
if (!$action) {
$actions = civicrm_api3($entity, 'getactions');
$result['actions'] = CRM_Utils_Array::makeNonAssociative(array_combine($actions['values'], $actions['values']));
}
CRM_Utils_JSON::output($result);
}
CRM_Utils_System::permissionDenied();
}
/**
* @param string $entity
* @param string|null $action
* @return array|bool
* [docblock, code]
*/
private static function getDocBlock($entity, $action) {
if (!$entity) {
return FALSE;
}
$file = "api/v3/$entity.php";
$contents = file_get_contents($file, FILE_USE_INCLUDE_PATH);
if (!$contents) {
// Api does not exist
return FALSE;
}
$docblock = $code = array();
// Fetch docblock for the api file
if (!$action) {
if (preg_match('#/\*\*\n.*?\n \*/\n#s', $contents, $docblock)) {
return array($docblock[0], NULL, $file);
}
}
// Fetch block for a specific action
else {
$action = strtolower($action);
$fnName = 'civicrm_api3_' . _civicrm_api_get_entity_name_from_camel($entity) . '_' . $action;
// Support the alternate "1 file per action" structure
$actionFile = "api/v3/$entity/" . ucfirst($action) . '.php';
$actionFileContents = file_get_contents("api/v3/$entity/" . ucfirst($action) . '.php', FILE_USE_INCLUDE_PATH);
if ($actionFileContents) {
$file = $actionFile;
$contents = $actionFileContents;
}
// If action isn't in this file, try generic
if (strpos($contents, $fnName) === FALSE) {
$fnName = "civicrm_api3_generic_$action";
$file = "api/v3/Generic/" . ucfirst($action) . '.php';
$contents = file_get_contents($file, FILE_USE_INCLUDE_PATH);
if (!$contents) {
$file = "api/v3/Generic.php";
$contents = file_get_contents($file, FILE_USE_INCLUDE_PATH);
}
}
if (preg_match('#(/\*\*(\n \*.*)*\n \*/\n)function[ ]+' . $fnName . '#i', $contents, $docblock)) {
// Fetch the code in a separate regex to preserve sanity
preg_match("#^function[ ]+$fnName.*?^}#ism", $contents, $code);
return array($docblock[1], $code[0], $file);
}
}
}
/**
* Format a docblock to be a bit more readable
* Not a proper doc parser... patches welcome :)
*
* @param string $text
* @return string
*/
private static function formatDocBlock($text) {
// Get rid of comment stars
$text = str_replace(array("\n * ", "\n *\n", "\n */\n", "/**\n"), array("\n", "\n\n", '', ''), $text);
// Format for html
$text = htmlspecialchars($text);
// Extract code blocks - save for later to skip html conversion
$code = array();
preg_match_all('#@code(.*?)@endcode#is', $text, $code);
$text = preg_replace('#@code.*?@endcode#is', '<pre></pre>', $text);
// Convert @annotations to titles
$text = preg_replace_callback(
'#^[ ]*@(\w+)([ ]*)#m',
function($matches) {
return "<strong>" . ucfirst($matches[1]) . "</strong>" . (empty($matches[2]) ? '' : ': ');
},
$text);
// Preserve indentation
$text = str_replace("\n ", "\n&nbsp;&nbsp;&nbsp;&nbsp;", $text);
// Convert newlines
$text = nl2br($text);
// Add unformatted code blocks back in
if ($code && !empty($code[1])) {
foreach ($code[1] as $block) {
$text = preg_replace('#<pre></pre>#', "<pre class='prettyprint'>$block</pre>", $text, 1);
}
}
return $text;
}
}
......@@ -86,19 +86,19 @@
<access_arguments>access CiviCRM;access AJAX API</access_arguments>
</item>
<item>
<path>civicrm/ajax/doc</path>
<page_callback>CRM_Utils_REST::ajaxDoc</page_callback>
<path>civicrm/api</path>
<page_callback>CRM_Admin_Page_APIExplorer</page_callback>
<access_arguments>access CiviCRM</access_arguments>
<title>CiviCRM API</title>
</item>
<item>
<path>civicrm/api/explorer</path>
<page_callback>CRM_Admin_Page_APIExplorer</page_callback>
<path>civicrm/ajax/apiexample</path>
<page_callback>CRM_Admin_Page_APIExplorer::getExampleFile</page_callback>
<access_arguments>access CiviCRM</access_arguments>
</item>
<item>
<path>civicrm/api/doc</path>
<aapage_callback>CRM_Utils_REST::APIDoc</aapage_callback>
<page_callback>CRM_Admin_Page_APIDoc</page_callback>
<path>civicrm/ajax/apidoc</path>
<page_callback>CRM_Admin_Page_APIExplorer::getDoc</page_callback>
<access_arguments>access CiviCRM</access_arguments>
</item>
<item>
......
......@@ -267,7 +267,7 @@ SET @devellastID:=LAST_INSERT_ID();
INSERT INTO civicrm_navigation
( domain_id, url, label, name, permission, permission_operator, parent_id, is_active, has_separator, weight )
VALUES
( {$domainID}, 'civicrm/api/explorer', '{ts escape="sql" skip="true"}API Explorer{/ts}','API Explorer', 'administer CiviCRM', '', @devellastID, '1', NULL, 1 ),
( {$domainID}, 'civicrm/api', '{ts escape="sql" skip="true"}API Explorer{/ts}','API Explorer', 'administer CiviCRM', '', @devellastID, '1', NULL, 1 ),
( {$domainID}, 'http://wiki.civicrm.org/confluence/display/CRMDOC/Develop', '{ts escape="sql" skip="true"}Developer Docs{/ts}', 'Developer Docs', 'administer CiviCRM', '', @devellastID, '1', NULL, 3 );
-- CRM-14435
......
{* file to handle db changes in 4.6.alpha6 during upgrade *}
UPDATE `civicrm_navigation` SET url = 'civicrm/api' WHERE url = 'civicrm/api/explorer';
\ No newline at end of file
......@@ -455,24 +455,6 @@ class CRM_Utils_REST {
CRM_Utils_System::civiExit();
}
/**
* Return smarty-generated API Documentation.
*
* @return string
*/
public static function APIDoc() {
CRM_Utils_System::setTitle("API Parameters");
$template = CRM_Core_Smarty::singleton();
return CRM_Utils_System::theme(
$template->fetch('CRM/Core/APIDoc.tpl')
);
}
public static function ajaxDoc() {
return CRM_Utils_System::redirect(CRM_Utils_System::url('civicrm/api/explorer'));
}
/**
* used to load a template "inline", eg. for ajax, without having to build a menu for each template
*/
......
......@@ -26,7 +26,7 @@
*/
/**
* File for the CiviCRM APIv3 acl functions
* This api exposes CiviCRM acl.
*
* @package CiviCRM_APIv3
* @subpackage API_acl
......
......@@ -26,7 +26,7 @@
*/
/**
* File for the CiviCRM APIv3 acl_role functions
* This api exposes CiviCRM acl_role.
*
* @package CiviCRM_APIv3
* @subpackage API_acl_role
......
......@@ -31,7 +31,6 @@
* @package CiviCRM_APIv3
* @subpackage API_ActionSchedule
*
* @copyright CiviCRM LLC (c) 2004-2014
*/
/**
......
<?php
// $Id$
/*
+--------------------------------------------------------------------+
| CiviCRM version 4.6 |
......@@ -28,12 +26,10 @@
*/
/**
* File for the CiviCRM APIv3 activity functions
* This api exposes CiviCRM activity.
*
* @package CiviCRM_APIv3
* @subpackage API_Activity
* @copyright CiviCRM LLC (c) 2004-2014
* @version $Id: Activity.php 30486 2010-11-02 16:12:09Z shot $
*/
......@@ -41,7 +37,7 @@
* Creates or updates an Activity.
*
* @param array $params
* Array per getfields documentation.
* Array per getfields documentation.
*
* @throws API_Exception
* @return array
......@@ -181,7 +177,7 @@ function civicrm_api3_activity_create($params) {
* ensuring mandatory requirements are met.
*
* @param array $params
* Array of parameters determined by getfields.
* Array of parameters determined by getfields.
*/
function _civicrm_api3_activity_create_spec(&$params) {
......
......@@ -26,13 +26,11 @@
*/
/**
* File for the CiviCRM APIv3 activity contact functions
* This api exposes CiviCRM activity contact.
*
* @package CiviCRM_APIv3
* @subpackage API_ActivityContact
*
* @copyright CiviCRM LLC (c) 2004-2014
* @version $Id: ActivityContact.php 2014-04-01 elcapo $
*/
/**
......
......@@ -26,13 +26,12 @@
*/
/**
* The activity_type api is deprecated. Please use the option_value api instead.
*
* @deprecated
*
* @package CiviCRM_APIv3
* @subpackage API_Activity
*
* @copyright CiviCRM LLC (c) 2004-2014
* $Id: ActivityType.php 30171 2010-10-14 09:11:27Z mover $
*/
/**
......
......@@ -26,13 +26,11 @@
*/
/**
* File for the CiviCRM APIv3 address functions
* This api exposes CiviCRM address.
*
* @package CiviCRM_APIv3
* @subpackage API_Address
*
* @copyright CiviCRM LLC (c) 2004-2014
* @version $Id: Address.php 2011-02-16 ErikHommel $
*/
/**
......
......@@ -80,8 +80,6 @@
*
* @package CiviCRM_APIv3
* @subpackage API_Attachment
* @copyright CiviCRM LLC (c) 2004-2014
* $Id: $
*/
/**
......
......@@ -26,7 +26,7 @@
*/
/**
* File for the CiviCRM APIv3 batch functions
* This api exposes CiviCRM batch.
*
* @package CiviCRM_APIv3
* @subpackage API_Batch
......
......@@ -26,11 +26,10 @@
*/
/**
* File for the CiviCRM APIv3 group functions
* This api exposes CiviCRM campaign.
*
* @package CiviCRM_APIv3
* @subpackage API_Campaign
* @copyright CiviCRM LLC (c) 2004-2014
*/
/**
......
......@@ -26,12 +26,11 @@
*/
/**
* File for the CiviCRM APIv3 Case functions
* This api exposes CiviCRM Case.
* Developed by woolman.org
*
* @package CiviCRM_APIv3
* @subpackage API_Case
* @copyright CiviCRM LLC (c) 2004-2014
*/
......
......@@ -26,12 +26,10 @@
*/
/**
* File for the CiviCRM APIv3 Case functions
* Developed by woolman.org
* This api exposes CiviCRM Case.
*
* @package CiviCRM_APIv3
* @subpackage API_Case
* @copyright CiviCRM LLC (c) 2004-2014
*/
/**
......
......@@ -29,10 +29,9 @@
* CiviCRM APIv3 pseudoconstants
*
* @deprecated
* The constant api is deprecated as of CiviCRM 4.4. Please use the getoptions api action instead.
* @package CiviCRM_APIv3
* @subpackage API_Constant
* @copyright CiviCRM LLC (c) 2004-2014
* @version $Id: Constant.php 30171 2010-10-14 09:11:27Z mover $
*/
/**
......
......@@ -26,18 +26,19 @@
*/
/**
* new version of civicrm apis. See blog post at
* http://civicrm.org/node/131
* @todo Write sth
* This api exposes CiviCRM contacts.
* Contacts are the main entity in CiviCRM and this api is more robust than most.
* - Get action allows all params supported by advanced search.
* - Create action allows creating several other entities at once (e.g. email).
* - Create allows checking for duplicate contacts.
* Use getfields to list the full range of parameters and options supported by each action.
*
* @package CiviCRM_APIv3
* @subpackage API_Contact
* @copyright CiviCRM LLC (c) 2004-2014
* $Id: Contact.php 30879 2010-11-22 15:45:55Z shot $
*/
/**
* Create or update a contact (note you should always call this via civicrm_api() & never directly).
* Create or update a contact.
*
* @param array $params
* Input parameters.
......
......@@ -26,11 +26,10 @@
*/
/**
* File for the CiviCRM APIv3 group functions
* This api exposes CiviCRM contact type.
*
* @package CiviCRM_APIv3
* @subpackage API_Survey
* @copyright CiviCRM LLC (c) 2004-2014
*/
/**
......@@ -63,12 +62,11 @@ function civicrm_api3_contact_type_create($params) {
}
/**
* Returns array of contact_types matching a set of one or more group properties.
* Returns array of contact_types matching a set of one or more properties.
*
* @param array $params
* One or more valid.
* property_name=>value pairs. If $params is set
* as null, all contact_types will be returned
* One or more valid property_name=>value pairs.
* If $params is set as null, all contact_types will be returned
*
* @return array
* Array of matching contact_types
......@@ -85,8 +83,7 @@ function civicrm_api3_contact_type_get($params) {
* to be deleted is required field in $params array
*
* @param array $params
* Array containing id of the group.
* to be deleted
* [id]
*
* @return array
* API Result Array
......
......@@ -26,13 +26,11 @@
*/
/**
* File for the CiviCRM APIv3 Contribution functions
* This api exposes CiviCRM Contribution.
*
* @package CiviCRM_APIv3
* @subpackage API_Contribute
*
* @copyright CiviCRM LLC (c) 2004-2014
* @version $Id: Contribution.php 30486 2010-11-02 16:12:09Z shot $