V2 Template guidelines

[Rinker]

Hi all,

I've been working once in a while on a module, but for a long time and now I started to upgrade the code for CMSMS2
Just want to know how to handle the 'summary' and 'detail' templates in a module, do I save them as a file, put them in my database or add them to the designmanager??
Keep in mind that the module works with 'groups' and each group have its own templates.
second:
If I have templates in the DB how do I display them?
From what I can see in the API docs, all functions seems file related and all (old) DB functions are deprecated.

How do we handle this kind of templates, must all passed to designmanager??

tia.,
Regards Robert

[Rolf]

<Off topic>
http://forum.cmsmadesimple.org/viewtopi ... 73#p325873
</Off topic>

[Rinker]

thnx Rolf, its already on my agenda, I'll be there if nothing else (important) comes up!

Trying not to be 'rude' now, but I do like an answer to my question so I can move on.

Regards,
Robert

[calguy1000]

There are two areas to discuss here:

a: Storage of Templates
CMSMS 2.x is the same as 1.x in that module developers have a choice to use file based templates, or database templates, or a combination of either depending upon the purpose of the module and the template.

- File based templates are stored in the modules/<modulename>/templates directory, and can be overridden by identically named files in the module_custom/<modulename>/templates directory.
- File based templates are typically used for templates used by the module's admin interface... but can be used for frontend actions to.
- File based templates require that users use the filesystem for managing files, and have intimate knowledge of the internals of how CMSMS works. editing the wrong file can cause complications with upgrading modules, and users have to have some knowledge of file system permissions, etc.
- Database based templates are for if your module will be publicly shared, will have multiple different instances of different types of templates (i.e: in News there can be multiple different Summary or Detail Templates).
- The new DesignManager and CmsLayout API's have more functionality than previous module template system allowing for unified editing, permissions, and additional editors.
- Templates using the new CmsLayout API's can integrate with the design manager, and be exported and imported to/from XML.

If you decide that your module should use database templates then you need to:
1. Create one or more Template Types
Here is an example of that (from News).

Code: Select all

try {
  $summary_template_type = new CmsLayoutTemplateType();
  $summary_template_type->set_originator($this->GetName());
  $summary_template_type->set_name('summary');
  $summary_template_type->set_dflt_flag(TRUE);
  $summary_template_type->set_lang_callback('News::page_type_lang_callback');
  $summary_template_type->set_content_callback('News::reset_page_type_defaults');
  $summary_template_type->reset_content_to_factory();
  $summary_template_type->save();
}
catch( CmsException $e ) {
  // log it
  debug_to_log(__FILE__.':'.__LINE__.' '.$e->GetMessage());
  audit('',$this->GetName(),'Installation Error: '.$e->GetMessage());
}

2. Create one or more templates for those types
Another example from News.

Code: Select all

try {
  $fn = dirname(__FILE__).DIRECTORY_SEPARATOR.'templates'.DIRECTORY_SEPARATOR.'orig_summary_template.tpl';
  if( file_exists( $fn ) ) {
    $template = @file_get_contents($fn);
    $tpl = new CmsLayoutTemplate();
    $tpl->set_name('News Summary Sample');
    $tpl->set_owner($uid);
    $tpl->set_content($template);
    $tpl->set_type($summary_template_type);
    $tpl->set_type_dflt(TRUE);
    $tpl->save();
  }
}
catch( CmsException $e ) {
  // log it
  debug_to_log(__FILE__.':'.__LINE__.' '.$e->GetMessage());
  audit('',$this->GetName(),'Installation Error: '.$e->GetMessage());
}

b: Fetching/Processing Templates
The 1.x module API had typically 2 functions for fetching/displaying templates:
- ProcessTemplate('somefilename.tpl');
- ProcessTemplateFromDatabase('sometemplatename');
In 2.x the way to do this has been simplified and rationalized to some extent.

Code: Select all

$tpl_ob = $smarty->CreateTemplate($this->GetTemplateResource($somestring));
$tpl_ob->assign('foo','bar');
$tpl_ob->display();

The GetTemplateResource() method will attempt to intelligently convert the string passed in to a smarty resource properly.
i.e: passing in 'sometemplate.tpl' will detect the .tpl extension and generate a module file template resource for reading the template from the modules/<ModuleName>/templates and module_custom/<ModuleName>/templates directories.
- passing in 'sometemplate' (without the extension) will assume a database template, and return a cms_template resource to read the template from the new CmsLayout API's and from Design Manager
- Passing a smarty resource such as file:something will do nothing.
This gives the module developer increased capabilities to allow the site builder to use different templates stored in different locations.

[Rinker]

Thanks Robert, this is a very clear answer.

I'll buy you a beer in March!

Again thnx!!!


Regards,
Robert