Frequently Asked Questions For Developers

This FAQ contains answers to the questions frequently asked by developers that are new to CMS Made Simple. Developers should look here first for an answer to their questions, before posting on the forge.

Q: How do I Include External PHP in my Page or Template

I have a script or a snippet of php code from my old site, and I want to include it into my new CMS pages. How do I do that?

A1: Using User Defined Tags (recommended)

You can create a user defined tag (under Extensions >> User Defined Tags) and include the php code there. i.e: create a php tag called my_phpinfo and in it, place this code

  phpinfo();  //(notice that the <?php and ?> tags aren't necessary).

Then you use the following syntax in your page to call that script:

  {my_phpinfo}

You can use any valid php code in a user defined tag, including the "include" command to include external scripts. You also have access to all of the CMS API, and global variables. This is the recommended way of including PHP code, as you can prevent people from editing this code via the permissions model.

A2: Using {php} and {/php} Tags

The second way to include php code into your page is by using {php} and {/php} tags to surround your php code in your page or template (you do not need the <?php and ?> tags with this syntax). However, this functionality is disabled by default on new installs.

To enable this functionality, you need to change one line of the config.php file in your installation. Change the "use_smarty_php_tags" setting to true. i.e.:

  #Allow smarty {php} tags?  These could be dangerous if you don't trust your users.
  $config['use_smarty_php_tags'] = true;

Now you can place php code into your page or template at will. i.e.:

  {php}phpinfo();{/php}

Note: This is not the recommended way of accomplishing this task, as any user with the ability to edit the page, or the template could edit the php code, and besides causing script errors, could potentially introduce security issues. Use a User-Defined tag instead.

Q: UDT vs plugins

Which is(are) the distinction(s) between UDT's and plugins?

A: Here main differences/properties

UDT's

 - stored in the database
 - are implemented as a single php function
 - are great when small and efficient
 - ideal for site-specific tasks (like event handlers)
 - don't have help and documentation

PLUGIN's:

 - are files in the plugins directory
 - are great for sharing between sites (just transfer the one file)
 - can have help and about information
 - can be a more complex (include multiple functions etc)
 - cannot be used as event handlers.

..."the choice of what to do use is up to you. but the general guidelines are... if it's small and/or site-specific, use a UDT... if it's larger and/or will probably be re-used on multiple sites, you may want to consider writing a plugin"...

source: forum

Q: Why don't Smarty Modifiers Work

I have a tag like:

  {content | lower}

in my template, and it doesn't do anything. What's wrong?

A: Because smarty isn't that smart about spaces

Smarty uses the space as a separator to indicate that it should be looking for an attribute to the tag, it uses the pipe character | to indicate the start of a modifier. Try making your code uglier and removing some whitespace like:

  {content|lower}

Q: Why can't I delete images or modules when I'm using FTP

Some users, particularly those used to the (cough) windows environment may be surprised that when they log into the web server with their assigned ftp username and password, that they can't delete certain files. Particularly modules, or things in the uploads directory.

A: Users can't delete another users files

BUT THEY'RE MY FILES!

No, they're not. Sorry. It's a Unix thing.

Most web hosting companies are using some flavor of Unix or a Unix-like operating system (mostly Linux these days). And usually, the web server process is running under a special user account (nobody, or apache, or httpd or something). Files it creates cannot be (by default) deleted by other users. Similarly, the httpd process owner (by default) cannot write into other user's directories. This is actually a good security measure. But it can get in the way.

When a file is uploaded to the uploads directory, or a module or theme is expanded from an XML file you upload, (or get from the Module Manager) then that file is owned by the httpd process user. Its permissions are set to that user's default file creation mode. And although other users can (usually) read the files, they probably can't write to them, or delete them.

So How do I fix it ?

Well, it's a two part answer.

1) You can fix it for files in a going forward situation, in CMS Made Simple by adjusting the file creation mask in the site preferences. This adjusts the httpd processes umask (user mask), and will effect the permissions of newly created files or directories. In brief, it works like this:

   File Permissions = 0777 - umask

i.e: If your file creation mask is 0022, the permission for a new directory would be 0777 - 0022 = 0755 Files would have similar permission, but would not have the execute bit set, and would be 644.

Here's a link to a rather exhaustive tutorial on unix file permissions: [1]

2) Any files that you've already uploaded and already can't delete will have to have their permissions opened up by the httpd process owner. Which means that a special script will have to be run. In CMS made simple 1.0, an ability to change permissions (and even remove) modules has been added.

However, there is a script rolling around that will let you recursively open up all files in a subdirectory, If you can't find it, contact calguy1000 he'll have it (hopefully).

Another Option

If you have the option of running CMS Made Simple in an suexec environment, where PHP runs as your user account, and that account (i.e. you) "own" the files that CMSMS (PHP) writes, then file and directory issues will be a thing of the past. Simple (usually default) permissions of 755 on directories and 644 on files are all that's needed in this environment (where your user account "owns" all the files and also runs PHP scripts). If you switch from one to another (i.e. move to suexec environment), you may need to ask your host to CHOWN everything in your CMSMS directory to your user account and set directories and files to the above defaults (755/644).

Can I access a module from within a plugin =

I'm writing a plugin or a UDT (User Defined Tag), and I'd really like to be able to interface with the XYZ module. How do I go about it?

Answer: Yes, via cms_utils::get_module()

You can work on a module trough the function cms_utils::get_module('TheModuleIWant').

Like:

  $themoduleiwant = cms_utils::get_module('TheModuleIWant');
  $themoduleiwant->DoThis($somedata);
  $themoduleiwant->DoThat($somemoredata);

Q: How do I change those hard coded module strings

Occasionally you want to change a string that is output from a module, and although this string is present in the <install dir>/modules/<ModuleName>/lang/xx_YY.php file, and easy enough to change, you wonder what will happen when you upgrade. Will your changes be lost?

Note: Some modules haven't been as nice with their string output, and literally hardcode the output. This isn't nice as in order to change things you have to actually modify the source. If you see this, please contact the module administrator and encourage them to fix the problem.

A: With your own lang file

It is possible to override any lang strings by creating a file structure and your own lang file that contains only the strings you want to change. The file structure needed is:

  <install dir>/module_custom/<ModuleName>/lang/xx_YY.php

You will want to copy the lines you want to change from the original lang file into this new file, and then change the strings as you see fit. See the FrontEndUsers example below (the commands are unix commands, you'll have to adapt differently for windows, or when working via ftp):

  cd /disk1/html/cms
  mkdir -p module_custom/FrontEndUsers/lang
  touch module_custom/FrontEndUsers/lang/en_US.php
  

Here I'll illustrate a couple of changed lines in the module_custom/FrontEndUsers/lang/en_US.php file:

  $lang['logout'] = 'Logout';  // changed from 'Sign Out'
  $lang['prompt_changesettings'] = 'Preferences'; // changed from 'Change My Settings'

Q: How can I debug my code/site

A: You can try these tools

For Internet Explorer (Windows):

• fiddler (http://www.fiddlertool.com) is a local proxy which allows to intercept and modify both sent and received stuff from the server. Perfect to test some js or css hack before putting it back in CMSMS.
• AIS Web Accessibility Toolbar (http://www.visionaustralia.org.au/info.aspx?page=614) allows (among other nice tools) to see exactly which CSS applies to the currently select element on a page

For Firefox (multi-platform):

• Firebug: See and debug AJAX requests and inspect page elements, edit CSS attributes on the fly, and more.
• Web Developer: In-page editing of CSS and HTML, examine and display CSS attributes, DIV and TABLE order, generated source (after scripts) code, resize browser window, and more.
• LiveHTTPheaders: allows you to see HTTP request and response headers.
• HTML Validator: (x)HTML validation right in your browser, also enhances "View Source" in Firefox.
• ColorZilla: Pick a color, any color, off a web page and copy it's RGB or hex value to clipboard.
• ScreenGrab!: Capture visible portion or entire page to an image.

Debug php code :

Lets say you have variable $entry in your UDT (User Defined Tag). Let's output it's content to the screen:

  var_dump($entry);     // outputs variable structure, also displays variable type and string length -
                        //important thing when debugging string encode/decode mismatch 
  var_export($entry);   // outputs variable structure as valid php code
  print_r($entry);      //outputs variable structure 
  
  echo '<pre>'; var_dump($entry); echo '</pre>';       // Now output is also nicely formated :) 

CMSms has its own debugging tools

  debug_display($entry);      // outputs nicely formated info, also displays time and memory usage
  debug_to_log($entry);       // writes info to '/tmp/cache/debug.log', file is created and appended

Debug sql in php code :

debug_to_log() is very useful function to inspect sql queries. Let's say $db is a database object:

  $count = $db->GetOne($query, $parms);
  debug_to_log($db->sql);         // just executed query is stored into file and is ready to be fixed :)

Debug smarty code :

First of all you have to know, what variables are available in template. Place following tag to your template (were it summary, details, page or any other template) and you will get variable list on you screen:

  {get_template_vars}

If variable 'entry' is not in a list try any other name that is listed (e.g. 'friendly_position' or 'content_obj' for more fun) Debugging Smarty variables is similar to php. We will use the same functions as in php code, but know they will be called Smarty variable modifiers. Yes, they are not standard Smarty variable modifiers.

  <pre> {$friendly_position|print_r} </pre>
  <pre> {$friendly_position|var_dump} </pre>
  <pre> {$friendly_position|var_export} </pre>
        {$friendly_position|debug_display}
        {$friendly_position|debug_to_log}
   
        {dump item=$friendly_position}

Writing array functions should be prepended with '@', but result usually is the same e.g. {$friendly_position|@print_r}. {dump} is a built-in CMSms tag, you can find out it's potential on "Extensions » Tags > dump".

You can also debug live site so that extra info is displayed only to your IP XXX.XXX.XXX.XXX.

  {if $smarty.server.REMOTE_ADDR=='XXX.XXX.XXX.XXX'}
     {$friendly_position|debug_display}
  {/if}

Developers FAQ

From CMSMS