CiviCRM Community Forums (archive)

At tonight's meetup in Washington, DC, one topic that came up is that some third-party developers implement PHP customizations using the Drupal API's (e.g. db_query) instead of Civi API's (e.g. CRM_Core_DAO). In my own experience, the reason I do this is because Drupal's community provides more robust developer documentation. Unfortunately, this has a few negative side-effects:

 * Code contains a mix of naming and formatting conventions (e.g. Drupal-style and Civi-style), making it harder to read and write.
 * Code is unnecessarily CMS-dependent. It works on Drupal -- but not Joomla (or standalone or Word Press, when/if that's implemented).
 * Code is not very suitable for sharing across organizational lines.

There has obviously been some good work going into improving the developer documentation -- with particular improvements for key use-cases (e.g. creating a custom CiviReport). But I haven't found a resource documenting the meat-and-potatoes of web application development -- e.g. defining new web controllers or executing SQL queries. The best option I've found is reading/grep'ing the current codebase for examples.

Based on that experience, I've written a first draft of a cheatsheet for PHP developers working with CiviCRM and/or Drupal -- a collection of small code snippets and hyperlinks organized around topics that any PHP application developer should recognize (e.g. "Logging", "SQL Query", "Web Forms"). It's pretty rough and very terse, but it might be useful for other devs:

h t t p : / / arms.dl.locker10.com/devel-doc/cheatsheet.html

Anyway, I'd appreciate any reactions/feedback/contributions.

Please don't read too much into the fact that I used "db_query/CRM_Core_DAO" as examples. Yes, api/v2 and api/v3 provide a safer way to CRUD current entities. Yes, api/v3 looks like a big improvement. And I hope to find an opportunity to try it out.             

Also, there is some good material/insights spread out among the flossmanual, the wiki, and the blog.  And where those fall short, one can often figure something out by critically reading Civi's code for 20 minutes.  I've been through that process.  Several times.

My feeling was that Civi's developer documentation is somewhat narrow -- it's decent-to-strong on some important points (e.g.  entity CRUD) and weak-to-non-existent on others (e.g.  pageflow mechanics).  Properly filling those gaps obviously requires a good chunk of work -- work whose value is debtable on a micro level ("Why should someone spend several hours writing about pageflow mechanisms?"). Anyway, the point of the draft cheatsheet was to try to cover broader ground in a concise and low-effort way.

The idea of joining in a wiki update project sounds nice in principle, but I'm not sure what it means in reality.

My feeling was that Civi's developer documentation is somewhat narrow -- it's decent-to-strong on some important points (e.g.  entity CRUD) and weak-to-non-existent on others (e.g.  pageflow mechanics).  Properly filling those gaps obviously requires a good chunk of work -- work whose value is debtable on a micro level ("Why should someone spend several hours writing about pageflow mechanisms?"). Anyway, the point of the draft cheatsheet was to try to cover broader ground in a concise and low-effort way.

Agree. I think that template, hook, api is well covered.

I'm not sure trying to document more the internals (DB_Object, quick form...) is really worthwhile the effort, as it will be replaced sooner? than later by more modern components. Mixed feelings on that one and I'm not quite sure how it vould boiled down to fit on a cheatsheet?

The idea of joining in a wiki update project sounds nice in principle, but I'm not sure what it means in reality.

Could you join the Api list ? We are going to discuss specifically the api part, and where it fits with the other civicrm/ajax/doc, autogenerated examples and the book.

http://lists.civicrm.org/lists/subscribe/civicrm-api

Hi,

Sorry, didn't "click" on the link (for those as blind as I am :
http://arms.dl.locker10.com/devel-doc/cheatsheet.html

In understand much better what you want to do/have done. I also think that's very helpful for the drupalers to translate between their framework and civi. Would be great to have someone from joomla adding their part. Some comments (I'm sure you have most of them already)

Usability suggestion: instead of radio buttons for the topics, simply put a link on their name

Design suggestion: would be nice to apply a nice theme (eg one from jquery-ui ?), http://visualjquery.com/ was always opened on a tab when I started jquery, in no small part because it was looking pretty

Content suggestion: the api is documenting the v2, would be great to put the v3 syntax first and add an "obsoleted" warning on the v2

API : I think http://sandbox.civicrm.org/civicrm/ajax/doc (and that's on every civi install as of 3.4) is cheating enough to be mentioned

About: CiviCRM: Extras: Data Access
* CiviCRM lacks an API for searching activities. arms_util_activity_search($params) fills this gap.

In theory, get actions have searching/filtering/paging features.
So far, contact is more advanced than the other entities, but I think lobo & Eileen are working on Activity.get soon (this week-end ?).

Anyway, whomever needs search options that aren't there are more than welcome to step in and add them to the get action (and so beside the api, that's also available on smarty and as web service).

X+

P.S. What is arms?

Tim, I think a cheat sheet or more robust Documentation for developers would be welcomed.

I love the way Drupal's API website is structured, I hope that's something that Civi can copy.

Some of the sentiment is echoed again with regarding to a lot of useful functions that CiviCRM provides.

i.e. PseudoConstant, Utils, etc etc.

Just a map of all the (static) methods, even if they are generated from reflection documentation in PHP would be helpful to developers beyond using the hooks and APIs.



Cheers!

Seems like the the clouds are lining up, the moon and sun are in alignment and the atmosphere has the right atomic mix for the formation of a documentation team

Lets get it started. As with everything else, lets start it small and focussed. get the doc site running, commit to writing good phpdoc stuff for the important core files and them figure out other things from there

glad to hear eileen promising t-shirts. I'll take a large please

lobo

1. I've made a few updates to the cheatsheet based on xavier's comments (e.g. change radio buttons to hyperlinks, reference API v3).

2. On the topic of documentation vs. major refactoring... I tend to agree with jalama. Unless there are concrete plans to overhaul several layers in the next 3 months, documentation about the status quo will still be valuable -- esp.  considering how much infrastructure has remained the same between CiviCRM 2.x - 4.x.

3. On the topic of phpdoc... I hadn't run phpdoc on the CiviCRM codebase before, but I did tonight.  It seems to be pre-configured to focus on the api v3 functions -- which I guess is used to build http://api.civicrm.org/v3/.  How is that site published now? I wouldn't mind throwing together some scripts to auto-publish nightly documentation sets for APIs+core on each branch.

Re phpdoc - Michau Mach set that up - if you can catch him on IRC he'd be the person to talk to.

OK, thanks.

In general, have you looked through the wiki / had any thoughts about how that might be better structured/ whether it's possible to incorporate some of your work / ideas into it?

I really like what you are doing but if you host it yourself you'll also have to maintain it yourself

I'll try to look at that in the next 24-48 hours. I do really like the idea of putting the content in a wiki so that others can edit it, but I need to play around with Confluence a bit. I feel that the little things (e.g. hyperlinks within code snippets, syntax highlighting, navbars) have a big cumulative affect on the way we read and write, and I need to understand Confluence's presentation options better.