Building Custom Admin Pages

The control panel provides automatically created admin pages for whatever database item types you create. This makes the system quick to set up, and minimizes the amount of effort needed to support a custom database structure.

There are times, however, when you want more control over the admin pages. There's two approaches you can take:

1. Customize the control panel pages using JavaScript.
2. Create front-end pages to replace selected control panel functions.

With the first technique, the pages remain part of the control panel; you modify the pages by injecting JavaScript (see Injecting JavaScript to Customize Control Panel Forms) or by creating configuration settings (see Customizing the Admin List Page for Custom Item Types).

Front-End Control Panel Pages

This article focuses on the second technique: creating front-end pages that perform control-panel functions.

Such pages should be set to "protected" (or "admin", if the membership system is enabled), so they can be viewed only by users logged in as admins. Data submitted from such pages will be rejected by the system if not created by a logged-in admin user.

The core technique is to mimic the control-panel pages in your front-end "admin" pages, so that the database system seems them as the same thing.

The simplest way to do this would be to copy the form code from a control-panel page, and then modify it as desired (perhaps removing fields and changing layout) and place it on a front-end page. However, when the form is submitted, the control-panel logic will redirect to the appropriate control-panel page (typically an items list page), taking the user our of your custom experience.

The way around this is to submit forms using JavaScript, instead of allowing a normal form submit. This keeps control on your custom page, and you can then redirect to whatever page you want after the submit completes.

Getting Key Values from the Control Panel

To find the required URLs and field names for writing to the database, view the source code for the control-panel form for creating an item fo the directed type. Then:

1. Keep only the code from <form> to </form>
2. Delete all the code after the </li> that ends the last data field, until the >/form< tag

You should then have something like this:

<form action="/admin/dy_schemas/9956/dy_nodes" class="cit-form form-demo_data" enctype="multipart/form-data" id="node_form" method="post">
  <ol id="outer-form-list">
    <li>
    <label for="demo_data_name">Name</label>
    <div class="input-wrap"><input class="text required" id="demo_data_name" name="demo_data[name]" size="50" type="text" /></div>
    </li>
    <li>
    <label for="demo_data_body">Body</label>
    <div class="wv_editor_container" id="demo_data_body"><div class="editor-controls group"><dl class="editor-view group"><dt>View:</dt><dd class="code current">Code</dd><dd class="visual">Visual</dd></dl></div><div class="textarea-wrap"><textarea class="editor" cols="80" id="demo_data_body_ta" name="demo_data[body]" rows="25" style="height: 400px;"></textarea></div></div>
    </li>
    <li>
    <label for="dymd_phone">Phone</label>
    <div class="input-wrap"><input class="text" id="dymd_phone" name="dymd[phone]" size="50" type="text" /></div>
    </li>
  </ol>
</form>

which here is stripped down to the essential information:

/admin/dy_schemas/9956/dy_nodes demo_data[name] demo_data[body] dymd[phone] The first item is the action to which the form is submitted; the next three are the names of the form fields. Let's assume that we have JavaScript variables with the data we want to store as part of a new item. We might set these by copying values from form fields, or from another calculation or communication. If, for example, we have a form that has ids with corresponding names, we could write:

var name = $("#name").val();
var body = $("#body").val();
var phone = $("#phone").val();

Now we need to write these values to the database. Here's the code:

      $.post('/admin/dy_schemas/9956/dy_nodes', {
          '_method' : 'post',
          " demo_data[name]": name,
          "demo_data[body]": body,
          "dymd[phone]": phone
         },
        function(data, textStatus){
            if (data.status == 'ok') {
                 // whatever page you want to redirect to when successful
            }
          else { console.log('item creation failed'); }    // add display of an error message
        },
        "json"); // $.post
        

This does the same thing as submitting the form to the database, except that browser isn't redirected to a new page.

You'll see here the four pieces of information that we pulled out of the code captured from the control panel page: the URL for the action, and the form field names for each of the values. The naming scheme is fairly simple, but not without its idiosyncracies, and you must get it exactly right or your data will not be saved. So pulling these names directly from the source view of a control panel page is the simplest way to get them right.

Modifying Database Items

In the example above, we created a new database item. You can use a similar technique to modify existing database items.

The two key differences are:

1. Must use a "put" method
2. Item ID required in the URL

Fields that aren't included in the data you submit will not be changed (with the exception of fieldsets, which require special care)

The URL to which the data must be posted is the same as for creating an item, with the addition of the item's database id, followed by "/edit". (You can see example URLs by editing items using the standard control-panel forms.)

Supppose, for example, we want to change the name of an item created by the preceding code to "George". The following code will do the job:

      $.post("/admin/dy_schemas/9956/dy_nodes/2005162/edit", {
          '_method' : 'put',
          " demo_data[name]": "George"
         },
        function(data, textStatus){
            if (data.status == 'ok') {
                 // whatever page you want to redirect to when successful
            }
          else { console.log('item creation failed'); }    // add display of an error message
        },
        "json"); // $.post
        

Note that the specifics of the post URL will need to be adjusted for your needs. The "9956" is the ID for the custom item type, and is common to both create and edit URLs.

The item ID, 2005162 in this example, determines the specific item that is being modified. Typically, your JavaScript code will have retrieved the item's previous values (including its ID), allowed the user to directly or indirectly specify some changes, and assembled the new data to be written.