Customizing Your Components

What’s a component?

A component is just a fancy name for a piece of content. Components are added to pages by a drag and drop editor and can be moved, edited, duplicated and deleted easily. Web Pro Manager comes pre-installed with many different components for placing text, images, navigation, forms and scripts onto your pages. You can also create your own components.

You can view the components installed in WPM in the Component Library. (Figure 3.1).

Figure 3.1 The Component Library lists the components currently installed in your WPM.



Why do I want to customize a component?

The pre-installed components come coded with some very basic formatting for each. For instance, the Title component surrounds the title displayed with <h1> HTML tags.

This pre-set formatting may not work for your template, especially if you have more complicated styles behind the look of your navigation, images, titles or text. In this case, you’ll need to override the pre-installed component’s formatting with your own desired formatting.

Customizing a component by overriding its display

By far the fastest way to get a component to look the way you desire is to override it for your template without changing the component directly.

Here’s how you do it:

  1. Create a sub-folder in your “tmpl” folder named “comp”, if it doesn’t exist already.

  2. Copy the component HTML file you wish to override from the “comp” folder in the root of your WPM installation to this folder. Note that the HTML file may be in a language sub-folder of “comp” (e.g. “comp/en”). Alternatively, you can also place the copied component in a language sub-folder in your “tmpl/comp” directory (e.g. “tmpl/comp/en”).

  3. You can now edit this file in any way you need and your component will display using the edited. Here’s an example of the code we updated for the Title component:
    BEFORE:
    <!-- BEGIN COMP: Title //-->
    [#text_BEFORE=<h1>_AFTER=</h1>#]

    AFTER:

    <!-- BEGIN COMP: Title //-->
    [#text_BEFORE=<h2 class=”special”>_AFTER=</h2>#]
  4. Upload your “tmpl/comp” directory to your WPM installation to see your changes.

Creating a new component

If customizing existing components just doesn’t cut it for you, the next best alternative is to create a completely new component.

Before proceeding, you might want to browse the files currently in the “comp” folder and sub-folders to get a feel of the components already installed with Web Pro Manager and how they work.

Here’s how you do it:

  1. To create a new component, you must first make a PHP configuration file which defines what your component does. It can be named anything, but must end in a ”.php” extension and reside in the root “comp” folder (e.g. “comp/mycomponent.php”). Without this file in place, the component will not install or run.

  2. In your new PHP configuration file, you will set a name and description of the component. You will also set a page-type limit which allows the component only to run on a certain type of page (e.g. Content, Homepage, or Search type only), and you will set an HTML template file for display of your component on the front-end website. To make sure your PHP configuration file is correctly formatted, you should copy the code from a default component that most resembles your new component.

    Here is an example taken directly from the Simple Text component’s PHP configuration file:
    <?php
    // Required settings
    $nName = "Simple Text";
    $nDescription = "Adds a space to enter in any text content or HTML.";
    $nPageTypeLimit = ""; // Content, Homepage, Search
    $nTemplateFile = "simpletext.html";
     
    addField("text","Title","(max. 200 characters)","","width:750px;");
    addField("textarea","Content","","","width:750px; height:200px;");
    addField("link-Page","Page Link","When 'more' is clicked on, choose a page to link to.","","width:300px;");
    addField("image-Button","Use This Button Image with Page Link","","","width:300px;");
    ?>


  3. With the name, description, page-type limit, and template set, you need to only add the fields that your component uses during editing and display. You do so with the “addField()” function. You can add as many fields as you like, of the same type or of different types.

    The addField() function accepts 6 parameters in this order:
    • {field ID} - determines how your field will be processed, choose ID from list below; field ID must be “text”, “textarea”, “linkid”(shows list of -Page or -Section), or “imgid” (shows list of images, add a dash and library name or default to “Content”).
    • {title} - title to display in the back-end during editing.
    • {caption} - caption to display in the back-end during editing
    • {default value} - default value in the back-end during editing
    • {field style} - CSS style in the back-end during editing
    • {template} - for lists (when field ID is 'linkid-Section') created during default processing, allows templating of individual list items using 2 tags: [#title#] and [#link#]

      Here are 3 addField() examples:
      // Adds a standard text field called Title
      addField("text","Title","(max. 200 characters)","","width:750px;","");
      // Adds a page navigation from a Section chosen by the user
      addField("linkid-Section","Build navigation from this Section","","","width:300px;","","basicnavitem.html");  
      // Adds a large textarea field called Content
      addField("textarea","Content","","","width:750px;","");


  4. Save your component PHP configuration file when finished.

  5. Create a new component HTML template file with the same name that you set for your template in Step 2 and save it in the same folder as your PHP configuration file, or in a language sub-folder underneath it. In it, add the HTML that will display when this component is used. For the parts of the component that are user-driven (every field you added in the component PHP configuration file), place a tag for that field.

    Here is a list of available tags and their parameters which will be replaced by the user’s chosen content.

    Following is an example taken directly from the Simple Text component’s HTML template file:
    <!-- BEGIN COMP: Simple text //-->
    [#text_BEFORE=<h1>_AFTER=</h1>#]
    <div id="contentBox">
    	[#textarea#]
    	[#linkedimage_NOIMAGE=more_SHOWUNLINKED=0_BEFORE=<BR><BR>#]
    </div>


  6. Save your component HTML template file when finished.

Related: Customizing Web Pro Manager