developer docs

[holtzermann17]

In order to facilitate new developers getting involved (or old developers getting re-involved), we should have some docs that give an overview of what we’ve done so far, some concise description and examples of hooks, themes, how to use jQuery with Drupal, etc.

Plan

We've been collecting a bunch of interesting pointers in the comments below and we also have a wiki page that provides the outline of a walkthrough of a couple examples. We should turn this into a proper narrative, with more code samples.

Installation

You don't want to have to click through the UI every time you install, so try this instead:

drush site-install [profile-name] --account-name=[admin_UN] --account-pass=[admin_PW] \
 --db-url=mysql://[db_user]:[db_pass]@localhost/[db_name] --site-name=Example

[profile-name] will be, for example, planetmath.

By the way: in general, Drush is awesome - check out this guide for some further details.

Places to ask questions

Of course any questions can go into the Planetary dev mailing list. We've also resolved to maintain a presence in the PlanetMath IRC channel, server irc.endernet.org, channel #planetmath.

You'll also want an account on drupal.org ("d.o.") and some acquaintance with the way they manage issue queues (e.g. make sure you mark "support requests" as such).

You can also ask generic Drupal questions on drupal.stackexchange.com. It's a great place to ask specific technical questions, especially if you're not getting help in the freenode #drupal-support IRC channel.

[holtzermann17]

The installation instructions should be pretty smooth sailing these days, but let me know if there are any adjustments.

It might be helpful to share my own first module which demos a way to query an RDF triple store from within Drupal. It also shows how to use Drupal's "menu system".

If you want to get your hands dirty (what better way to learn), you might want to check out the Hotfix and Code Cleanup milestones. Always fair game for something small to improve or investigate.

Writing Drupal modules is sort of confusing until you know what you're doing! Luckily there are some very savvy people on the team who can help you. Ask questions often.

If I could suggest a couple additional modules as good examples to learn from,

The correction module is by Alex and the problem module is by me, modeled after Alex's code. This doesn't show you all the "tricks", but it does give an example of how to adapt a module that does "almost" what you want.

Use the source! -- you'll want these tools:

• dd - you can use this almost everywhere (prints things to /tmp/drupal_debug.txt)
• dpm - useful for investigating complicated objects, but doesn't work in every instance
• dpm(debug_backtrace()); - useful for figuring out how you get into a given block of code
• You can use var_dump if dpm doesn't work.
• Another nice trick is print_r($array,TRUE) which gives you something you can sorta copy and paste into code.
• dd(array_keys($content)); is a nice way to get a succinct overview of the contents of an array, e.g. when you're rendering individual elements of an array in some template.
• dpm(unserialize(...)) to make a readable version of serialized contents stored in MySQL

If you want to use dd in combination with drush, see this answer on SE.

[holtzermann17]

Wildcards when defining a menu can be a little confusing unless it's spelled out.

Consider the path foo/bar/baz -- here bar occupies place 1. Thus, for example, we define the following menu item:

  $items['problems/%/attach'] = array(
      'title' => 'Attach problem',
      'type' => MENU_CALLBACK,
      'page callback' => 'problem_attach_problem',
      'page arguments' => array(1),
      'access arguments' => array('create correction content')
  );

Similarly, baz occupies place 2, and so we might define a more complicated menu item with multiple wildcards as follows:

  $items['problems/confirm/%/%'] = array(
      'title' => 'Confirm attachment',
      'type' => MENU_CALLBACK,
      'page callback' => 'problem_confirm_attachment',
      'page arguments' => array(2,3),//'nid_of_article','nid_of_problem'),
      'access arguments' => array('create correction content')
  );

In short, count the number of slashes, not the number of wildcards.

[holtzermann17]

Note that you can do more with drush than you might have thought -- for example, there's no drush command to rebuild permissions, but you can just do drush php-eval 'node_access_rebuild();'.

[holtzermann17]

If you're actively developing Drupal modules, it's helpful to have an interactive debugger. (Note: this section is strictly optional, and only of interest to developers.)

Like Drupal, Drush has its own sub-projects. To give yourself a comfortable interactive debugging environment, first download phpsh, and follow the provided installation instructions, minimally:

git clone git://github.com/facebook/phpsh.git
cd phpsh
python setup.py build
sudo python setup.py install

There's some preliminary drush integration but it only works so-so. (And it does NOT work well at all if you have Xdebug turned on.)

To get what's there, first install the Drush compatibility layer:

cd ~/.drush
git clone --branch master http://git.drupal.org/project/phpsh.git

Subsequently, you can run:

$ phpsh
php> r ~/.drush/phpsh/includes/console_7.inc
php> node_load(...);

If you apt-get install exuberant-ctags, you can then use drush phpsh-ctags to build an index of documentation, which you can then read interactively.

[holtzermann17]

If you feel like you need to be a Github power user for a period of time, you can download and install GHI, which provides a CLI for Github.

[holtzermann17]

Issue reporting

• use the LaTeXML Trac for LaTeXML-specific issues that show up in PlanetMath, but that are ultimately relevant to other LaTeXML installations;
• use the Planetary issue tracker for LaTeXML customizations that are only relevant to PlanetMath or other Planetary deployments;
• use the PlanetMath issue tracker for PM organizational, strategic, and documentation issues

[holtzermann17]

I added the outline of some narrative-form Developer Docs to this wiki page:

https://github.com/KWARC/planetary/wiki/Getting-Your-Hands-Dirty-With-Drupal

[dginev]

Seems like a good start, but it has a bunch of questions intermixed with the answers... I guess making it a bit more structured and instructive would help -- getting the hang of the way Planetary so far prefers hooking into Drupal, already in the very beginning, is extremely important to keep developers on board.

As I like pointing out, being stuck for too long with not finding my way around Drupal was the reason I stopped contributing to Planetary when the Drupal port started.

[holtzermann17]

@dginev yes, these do need improvements. I'll try to make the docs that exist here coherent enough to get included into the PlanetMath site docs collection for starters. I made a PM ticket about it here: holtzermann17/planetmath-docs#56 and will aim to get a version 1.0 done in time for that milestone (1 month).

[holtzermann17]

I revised the wiki page, bringing in most of the points from this ticket.

https://github.com/KWARC/planetary/wiki/Planetary-Developer-Docs:-Drupal-by-Example

As the new title indicates, I think it would be good to go through each of the important examples of things people need to do as programmers, one by one. I've gotten started with this but it will need more work. I hope when there are a few more examples of examples, I can more easily enlist help from others!

[dginev]

The Drupal-by-Example page has gone way out of hand - too much content and too much chaos over there.

I'm leaving the US and flying home for the holidays next week, so hopefully I will find the time to do some work on Planetary (I want to prepare a clean minimal installation and clean minimal introductory documentation that is friendly to devs).