Plugins

Plugins

Plugins make it easier for the CMS users to edit page elements by abstracting away the HTML editor to more manageable interfaces. Below are some examples of plugins.

• A book plugin for managing a list of books. The user fills out a form containing the author, title, etc. and the plugin generates and inserts the formatted HTML block.
• A form plugin for creating HTML forms. The user adds, edits, and deletes form inputs (dropdown menus, text inputs, checkboxes, etc.).
• A users plugin that stores user data for a number of users, including name, date of birth, sex, etc. and displays them in a number of different formats (table, list, etc.).
• A password plugin where a user enters a password and the md5 hash of it is stored.
• A task plugin for managing a list of tasks. The user enters the due date and description and the plugin inserts it, keeping the list in chronological order.

A plugin outputs HTML, javascript, and CSS code that manipulates the standard edit page. There is an included plugin generator that makes it easy to handle plugins like the book example above that consist of a list of formatted HTML blocks. There is also a more generic plugin generator that stores a CSV file instead of HTML code that can be used when the data determines the output code (forms example) or when you want to separate the content from the formatting (users example).

Plugin Generator

The plugin generator is called within a plugin file and outputs the required HTML, javascript, and CSS to produce a nice looking, easy to use interface for managing lists of HTML blocks. For the book example, an HTML block for a book might look like this:

<strong>Title of Book</strong> by <em>Author Name</em> (<span>genre</span>)
<p>Description of book.</p>

The basic syntax for the generator function looks like this:

<?php
generate_plugin($name,$template,$parameters = array());
?>

Here are detailed descriptions of the various parts of this function.

• $name - The name of an HTML block ("book", "task", etc.). Each block will be wrapped in a div with this class unless the $nodivs parameter is set.

• $template - The actual HTML code for a block with fields specified as follows:

  <?php
  //basic way to specify fields
  $example = "[[$field_name][$field_type]]";
  
  //individual fields from book plugin
  $title = "[[title][text]]";
  $author = "[[author][text]]";
  $description = "[[description][textarea]]";
  
  //select fields (i.e. genre) using helper function
  $genre = generate_select_field("genre",array(
      "horror"=>"Horror",
      "mystery"=>"Mystery Novel",
      "nonfiction"=>"Non-fiction"
  ));
  
  //manual select fields
  //syntax of options: "[value1|display1||value2|display2||value3|display3]"
  $genre = "[[genre][select][horror|Horror||mystery|Mystery Novel||nonfiction|Non-fiction]]";
  
  //complete book example
  $template = "<strong>[[title][text]]</strong> by <em>[[author][text]]</em> (<span>" .
              generate_select_field("genre",array(
                  "horror"=>"Horror",
                  "mystery"=>"Mystery Novel",
                  "nonfiction"=>"Non-fiction"
              ))."</span>)
              <p>[[description][textarea]]</p>";
  ?>
  

• $parameters - An array of options that effect how the plugin works.

  • "nodivs"=>"element" - Used for simple HTML blocks that consist of only one main tag (list of paragraph tags, elements in an OL or UL list, list of links, etc.). "element" refers to the tag name ("p", "li", "a" from the previous examples).

  • "selectors"=>array("field_name"=>"jquery selector") - A list of jQuery selectors to get the elements containing the various fields relative to the HTML block. If this parameter is missing, or if a field is left out, it will not be pre-filled in the edit dialog. For the book example, it would be:

    <?php
    array(
        "title"=>"strong",
        "author"=>"em",
        "description"=>"p",
        "genre"=>"span"
    )
    ?>
    

  • "editable"=>array("field_name","field_name2") - A list of select fields that are editable. If a field appears in this list, the select box will turn into a combobox and the user can enter their own value by clicking the select box and typing.

Putting it all together, to create a book plugin, you would put the following code in "book.php" in the /site/cms/plugins/ folder. Notice how you can style the preview box directly with CSS.

<style>
#cms_preview .book {
    border:1px solid black;
    margin: 5px;
    padding: 5px;
}
#cms_preview .book em {
    font-size: 80%;
    color: #333333;
}
</style>
<?php
generate_plugin(
    'book',
     "<strong>[[title][text]]</strong> by <em>[[author][text]]</em> (<span>" . generate_select_field("genre",array(
            "horror"=>"Horror",
            "mystery"=>"Mystery Novel",
            "nonfiction"=>"Non-fiction"
        ))."</span>)\n<p>[[description][textarea]]</p>",
    array(
        "title"=>"strong",
        "author"=>"em",
        "description"=>"p",
        "genre"=>"span"
    )
);
?>

To use this plugin for a page element, you can add the following code to the page description:

<?php
$special_handling = "book";
?>

CSV Plugin Generator

The CSV plugin generator is called within a plugin file and outputs the required HTML, javascript, and CSS to produce a nice looking, easy to use interface for managing a CSV file. When calling this function, you specify the CSV headers and provide a javascript callback function for formatting a row that is used to generate live previews. Below is an example of the CSV file for a users plugin:

"name","dateofbirth","sex"
"John Doe","3/1/1940","male"
"Jane Smith","1/4/1976","female"

The basic syntax for the CSV generator function looks like this:

<?php
generate_csv_plugin($name,$parameters = array());
?>

Here are detailed descriptions of the various parts of this function.

• $name - The name of the plugin (no spaces). This determines the callback function to use and helps style the live preview.

• $parameters - This is an associative array that gives the generator info on how to create the plugin. Below are the possible array entries:

  • "fields"=>array("field_name"=>array("label"=>"","id"=>"","type"=>"","options"=>"")) - A description of the columns in the CSV file. Below is an example for the users plugin:

    <?php
    array(
        'name'=>array(
            'label'=>'Name',
            'id'=>'name',
            'type'=>'text'
        ),
        'date_of_birth'=>array(
            'label'=>'Date of Birth',
            'id'=>'date_of_birth',
            'type'=>'date'
        ),
        'sex'=>array(
            'label'=>'Sex',
            'id'=>'sex',
            'type'=>'dropdown',
            'options'=>array('male','female')
        )
    );
    ?>
    

  • "editable"=>array("field_name","field_name2") - A list of select fields that are editable. If a field appears in this list, the select box will turn into a combobox and the user can enter their own value by clicking the select box and typing. An example of this would be if you wanted the user to be able to specify their own value for the "sex" dropdown field in the users plugin.

  • "format_function"=>"function name" - The name of the javascript callback function. If this value is not set, the function "format_{plugin_name}" will be used. For example, if the plugin name is "users", the default function will be "format_users".

In addition to passing these parameters to the generate_csv_plugin() function, you also need to provide a javascript formatting callback function. This function takes an array of values for a row and returns formatted HTML code. Here is an example of the format_users function:

function format_users(values) {
    //values in same order as 'fields' parameter
    var name = values[0];
    var dob = values[1];
    var sex = values[2];

    //return formatted HTML block
    return "<strong>" + name + "</strong> (" + sex + ") was born in " + dob + ".";
}

The HTML block returned from the format function is then wrapped in a div and displayed along with edit, delete, move up, and move down links. Putting everything together, here is the complete contents of the users plugin file:

<script type='text/javascript'>
function format_users(values) {
    //values in same order as 'fields' parameter
    var name = values[0];
    var dob = values[1];
    var sex = values[2];

    //return formatted HTML block
    return "<strong>" + name + "</strong> (" + sex + ") was born in " + dob + ".";
}
</script>
<?php
generate_csv_plugin('users', array(
    'fields'=> array(
        'name'=>array(
            'label'=>'Name',
            'id'=>'name',
            'type'=>'text'
        ),
        'date_of_birth'=>array(
            'label'=>'Date of Birth',
            'id'=>'date_of_birth',
            'type'=>'date'
        ),
        'sex'=>array(
            'label'=>'Sex',
            'id'=>'sex',
            'type'=>'dropdown',
            'options'=>array('male','female')
        )
    )
));
?>

Custom Plugins

The plugin generators don't work for every situation, so there may be some times when you need to write a custom plugin. There are no restrictions on what a plugin can do or how a plugin file is laid out, but these guidelines and code snippets should help you get started developing one. Keep in mind that jQuery 1.4.4 and jQueryUI 1.8.9 are preloaded, so don't hesitate to take advantage of them.

• Hiding the HTML editor and providing a "show code" link

  <script type='text/javascript'>
  //create hide/show link
  var link = $("<a>").attr('href','#').text('Show Code').css('font-size','.7em').click(function() {
      //toggle HTML editor
      $("#dsrte_holder").toggle();
  
      //change link text
      if($("#dsrte_holder").css('display') == 'none') {
          $(this).text('Show Code');
      }
      else {
          $(this).text('Hide Code');
      }
  
      return false;
  });
  
  //hide by default and add link before editor
  $("#dsrte_holder").hide().before(link);
  </script>
  

• Creating a preview box and rendering HTML editor code on the fly

  <div id='cms_preview' style='width: 600px; border: 1px solid #888; height:350px; margin-top:20px; overflow:auto;'></div>
  
  <script type='text/javascript'>
  //renders HTML code
  function updatePreview() {
      $("#cms_preview").html($("#dsrte_text").val());
  }
  
  //bind update function to various events
  $(document).ready(updatePreview); //when page loads
  $("#dsrte_text").keyup(updatePreview); //while typing in HTML editor
  #("#some_button").click(updatePreview); //when some button is clicked
  </script>
  

• Getting text from an input and filtering it before adding it to the HTML source

  <div id='input_form'>
      Lowercase Word: <input type='text' id='lowercase_input' />
      <a href='#' id='lowercase_submit'>Make uppercase</a>
  </div>
  
  <script type='text/javascript'>
  $("#lowercase_submit").button().click(function() {
      var text = $("#lowercase_input").val();
  
      text = text.toUpperCase();
  
      $("#dsrte_text").val($("#dsrte_text").val() + " " + text);
  
      return false;
  });
  </script>