Admin Manual - Customization
From PikaDocs
| Table of contents |
What Customization Can Do
Most programs need to track specialized data for local funding sources. With this in mind, Pika provides a framework for customizing the case, contact and activity screens. Data fields can be added or removed, the order and layout of fields can be changed, and case tab screens can be added or removed. This document will walk the reader, step by step, through the process of using the Pika customization framework. These instructions assume you have read Preparing Your PC and have set up a P: drive to your Pika site, and have installed MYSQLCC and Macromedia Dreamweaver on your desktop PC. (Other software can be used in place of MYSQLCC and Dreamweaver, if you have a preference, but these instructions may not match completely with other applications.)
Adding a New Field to Pika
The procedure for adding a new field to a Pika screen consists of four steps. First, add a column to a database table to store the contents of this field. Second, make Pika aware that a new field has been added for that table. Third, the field can be added to that screen's HTML template file. Finally, a copy is made of the modified file so it can be re-applied after future upgrades.
Adding a Database Column
- Start MYSQLCC.
- Connect to the database server.
- Connect to the Pika database on the server.
- Right click on the table and select “Edit Table” on the menu.
- Highlight the last row on the field list.
- Select Table->Insert Row from the menu.
- Enter the field name (in this example, it is new_field).
- Check off Allow NULL if blank values should be allowed in this field.
- Select the datatype for the field. Choose a column type that matches the type of data that will be stored. For example, if a field will store a “yes/no” value, use TINYINT. “Yes” will be assigned a 1 value, and “No” will be assigned a 0 value. For a text field, use a VARCHAR or TEXT column.
- Change the field length and default value, if desired.
- Select File->Save from the menu.
- Exit MYSQLCC.
Scan for New Fields
Pika CMS maintains an internal list of all data fields in use by the system, so the system doesn't need to be re-programmed every time a new field is added. When you add a new column to a table, Pika needs to be notified that the new column exists.
- Log into Pika.
- Open the Site Map.
- Click “Scan for New Fields”, under the Administrative section of the Site Map.
Edit the HTML Template File
The next step is adding the field to the template file for the desired screen. Every form in Pika has an HTML file which serves as a template for the form's layout. The template files are in HTML format, so any web page editor can be used for editing. These template files are found in subtemplates in the Pika directory on the server. You can determine what template file is used for a screen by looking the file name.
- Load the template file in the editor. Most template files are found under P:\sitename\subtemplates.
- Examine the file and verify that you have loaded the correct template.
- Enter a label for the new field wherever you want it to show up in the form.
- Below the label, enter the code for this field, i.e. %%[field_name menu source=menu_name]%% Be sure to set the field name so that it is identical to the field name in the data field listing and the database column name. menu_name should match the name of the menu to be used for this field.
- Select File->Save on the menu.
- Log into Pika and open this screen. Verify that the new popup menu field is displaying properly.
- You are not limited to adding only popup menu fields. There are several different types of fields that can be added, see HTML Fields and Template Tags for a full description.
Copy the Modified HTML Template File
The newly edited template file will be overwritten the next time the site is upgraded to a newer version. To preserve the changes you have made, copy the file to the directory P:\custom-sitename. For example, if you add a new field to P:\sitename\subtemplates\caseinfo. html, copy that file to P:\custom-sitename\subtemplates\caseinfo. html. The next time the site is upgraded, any files in the custom-sitename will be copied over the new version of Pika, restoring all previous customizations.
Removing an Unneeded Field
- Load the template file in the editor.
- Highlight the field to be removed with the mouse.
- Press the Delete key.
- Select File->Save on the menu.
- Log into Pika and verify that the field no longer appears on the screen.
Adding a New Menu
Sometimes you will have a new field where none of the standard Pika menus will do the trick, and you will need to add a new menu to the system. When adding a new menu to Pika, first decide on a name for the menu. Menu names should be descriptive, and should not include any spaces. The menu name will be used on the HTML form templates to specify where to display said menu. Next, you must manually add the table which will store it, using MYSQLCC. Menu table names should be the menu name with a "menu_" prefix. For example, if you are adding a menu called "funding", name the database table menu_funding. The table should have a value, label, and menu_order column. It may be simplest to make a copy of an existing menu table and rename it as necessary. Once the database table is created, you can edit the contents of the menu by clicking on the menu name from the Menu Management screen.
Editing a Menu
Each line in the text box on the menu editor screen corresponds to an entry that will be displayed on menu. Each line has two values, separated by a "|", or pipe, symbol. The first value is the actual value that will be stored when a user selects that menu item on a form. The second value is the label that will appear on the menu.
Adding a New Case Tab
- Decide on a name for the new case tab. In this example, we will use “newtab”.
- Create a new HTML file called P:\pika_site\subtemplates\case_newtab.html. It will save you time to copy an existing template file, such as case_info.html, and use that as a starting point.
- Use your HTML editor to create the form that should appear on the new case tab.
- Every case tab needs a definition file in the P:\pika_site\modules\ directory. Copy an existing definition file, such as case-info.php, and name it case-newtab.php. Again, use this as a starting point.
- Make any changes to the PHP code in case-newtab.php that might be required for the operation of the new case tab. Be sure to edit the last call to pl_template() to have it use case_newtab.html
- Log into Pika.
- Open the Site Map.
- Click on Menus and Special Tables.
- Click on case_tabs
- Add a new row that reads:
newtab | The New Tab
- Click the Save button.
- Open a case record from Pika and verify that the new case tab appears and displays correctly when clicked.
