Invoke and include a separate .php from within a callback for a drupal 6 page

I'm new to Drupal (v6) and PHP, and I'm trying to implement some content through a custom module. I've followed a tutorial, and figured out how to make Drupal aware of my module and even registered a URL for my custom page. It's appearing in the navigation as I intended -- so far so good.

This is great for my toy example... but less good for the page(s) I actually intend to write. Right now I have this:

function twtevents_menu() {

  $items = array();

  $items['gingerbread'] = array(
    'title' => 'Gingerbread Gallery',
    'page callback' => 'twtevents_gallery_gingerbread',
    'access arguments' => array('access twtevents content'),
    'type' => MENU_NORMAL_ITEM
  );

  return $items;
}

function twtevents_gallery_gingerbread() {
  // content variable that will be returned for display
  $page_content = '';

  $page_content = '<p>'.  t("Some super-cool content") .'</p>';

  return $page_content;
}

But I don't want to write a large, complex page in the style of $page_content = '<p>'. t("Some super-cool content") .'</p>'; -- and on and on.

I want to write the actual page in a style closer to this:

<div class="comment<?php print ($comment->new) ? 开发者_Python百科' comment-new' : ''; print ' '. $status ?> clear-block">
  <?php print $picture ?>

  <?php if ($comment->new): ?>
    <span class="new"><?php print $new ?></span>
  <?php endif; ?>

  <h3><?php print $title ?></h3>

</div>

Where php code is sprinkled into HTML markup, rather than the reverse.

From within my function, I can call include($path) successfully, but (of course) this approach just places the output of my page in the top-left cornet of the broser... I need to send the output of the separate page as the return of my callback function.

Is there a PHP function for this? A Drupal function? Best practices?

To use your custom template file in a module, you should provide your hook_theme implementation. Below there is an example from advanced forum module.

function advanced_forum_theme() {
  // ...
  $items['advanced_forum_topic_header'] = array(
      'template' => 'advanced_forum-topic-header',
      'arguments' => array(
        'node' => NULL,
        'comment_count' => NULL,
        )
  );
  // ...
  return $items;
}

This is how the hook is invoked:

  // Build the topic header
  $variables['topic_header'] = theme('advanced_forum_topic_header',
                                      $variables['node'],
                                      $variables['comment_count']);

The template file that contains the layout is advanced_forum-topic-header.tpl.php.

Some links for more details: "Using hook_theme to style module output", hook_theme description for Drupal 6.

As Kniganapolke says, you want a hook theme implementation to call a template;

Something like;

function twtevents_theme(){
    return array(
        'template' => 'twtevents_gallery_gingerbread',
        'arguments' => array()
    ); }

Then place your template code into a file called twtevents_gallery_gingerbread.tpl.php in your module folder.

Then update your page callback to call the theme function like this;

function twtevents_gallery_gingerbread(){
    return theme('twtevents_gallery_gingerbread');
}

Now here is the important bit - once you've added the theme hook to your module you must clear your Drupal cache, otherwise it won't find your new template.