How to theme a custom object from an external datasource?

Question

I am building a Drupal 7 website that has several Content Types (CTs) like Page, Event, Blog etc. For each CT, the full node view mode has been heavily customized using Display Suite.

I am requested to display data (let's say articles) from an external datasource (remote json API) within my website. Each remote article should be displayed in a single page within my website (like full node view modes), should look like (similar if not the same HMTL markup) as in my normal Drupal nodes and should not be persisted.

In a custom module, I have implemented hook_menu and defined a custom page callback, and within my callback, I perform the remote API request for a remote article (let's assume that remote article identifiers are available to me) and parse the json into a php object.

function my_custom_module_menu() {
  $items = array();
  $items['foo/bar/article/%'] = array(
    'title' => 'Remote article page',
    'page callback' => '_remote_article_display',
    'page arguments' => array(3),
    'type' => MENU_CALLBACK,
  );
  return $items;
}

function _remote_article_display($article_id) {
  // unrelated remote request and json parsing code 
  $article = get_remote_article_by_id($article_id);
  $output = ''; // how to theme $article object?
  return $output;
}

How should I print the proper HTML markup for my $article object without hardcoding it? The fact that my normal nodes are using Display Suite is an additional overhead as at this point I am not even sure how to print the default Drupal html for fields.

Answer 1

You should use hook_theme() for that:

Register a module (or theme's) theme implementations.

The implementations declared by this hook have two purposes: either they specify how a particular render array is to be rendered as HTML (this is usually the case if the theme function is assigned to the render array's #theme property), or they return the HTML that should be returned by an invocation of theme(). See Using the theme layer Drupal 7.x for more information on how to implement theme hooks.