Help!

Or search support forum

What's Global Moxie?

Global Moxie specializes in mobile design strategy and user experience for a multiscreen world. We offer consulting services, training, and product-invention workshops to help creative organizations build tapworthy mobile apps and effective websites. We're based in Brooklyn, NY. Learn more.

On Shelves

Books by Josh Clark

Tapworthy: Designing Great iPhone Apps

Best iPhone Apps: The Guide for Discriminating Downloaders

iWork ’09: The Mising Manual

Moxiemail

Enter your e-mail to receive occasional updates:

Can I add additional data fields to my Big Medium pages?

Important: Sales, service, and support of Big Medium are no longer offered. More details.

Question

Can I add additional data fields to my Big Medium pages?

Answer

You betcha. You do this by creating a custom code plugin for Big Medium. This requires wading through a bit of code, but this tutorial includes a sample plugin that you can use as a template. Depending on your needs, you may even be able to use the plugin as-is.

This page walks through all of the code and describes exactly how the plugin works. You may find this useful if you're a developer or if you’re otherwise curious how Big Medium plugins work. If you prefer not to know the gory details (ignorance is, after all, bliss), you can skip to the installation section below.

Anatomy of the Plugin

Our example plugin will add two new edit fields to your pages:

  1. A “secondary content” field that you can use to display a second block of content on your pages, separate from the page’s main content

  2. An “edit history” field where you and other editors can add internal notes about a page as it goes through the editing process

Our plugin will consist of three files, all of which will get installed into your Big Medium installation’s moxiebin/plugins directory:

  • add-fields-register.pl
    This file registers your plugin with Big Medium, telling it to load the other two files at the appropriate time to do the actual heavy lifting.

  • add-fields.pm
    This file contains the code that adds your new data fields to Big Medium’s default fields for pages. It also tells Big Medium where to add the fields in the page edit screen.

  • add-widget.pm
    This file contains the code to create a custom widget to display the contents of your new fields.

Registering the plugin

Big Medium loads plugins by running scripts ending with .pl in its moxiebin/plugins directory. That means that add-fields-register.pl will run each time that you run Big Medium. Its job is to let Big Medium know about the existence of the other two files in our trio and when exactly it should load them.

We want Big Medium to load add-fields.pm whenever it needs the data definition of a content page. And we want to load add-widget.pm whenever Big Medium needs to know how to build HTML pages.

The resulting add-fields-register.pl file is short ’n’ sweet:

package BMplugin::AddFields;
use BigMed::Plugin;
use strict;
use warnings;

#when loading content definitions, load add-fields.pm
BigMed::Plugin->add_content('add-fields.pm');

#when loading page format definitions, load add-widget.pm
BigMed::Plugin->add_format('add-widget.pm');

1;
__END__

Defining the new fields

The add-fields.pm file is responsible for adding the new fields to Big Medium’s page data structure and inserting the new fields into the edit screen.

There are a few steps to doing this, so rather than display all of the code at once for add-fields.pm let’s chunk it up into its key elements. The add-fields.pm in the downloadable plugin zip (in the installation section below) contains the final product, including comments explaining how to customize it.

Data structure

A data-field definition is composed of just a few pieces of information:

  • The field’s internal name
  • The field’s data type
  • The field’s default value in the edit screen

For the purposes of this plugin, we’ll also add one other piece of info:

  • The edit panel in which the field should appear on the edit screen

The top of the add-fields.pm file creates this data definition like so:

package BMplugin::AddFields;
use strict;
use warnings;

my @new_fields = (

    #content2 field definition
    {   name       => 'content2',
        type       => 'rich_text_brief',
        default    => '',
        page_panel => 'bmfsPageContent',
    },

    #comments field definition
    {   name       => 'comments',
        type       => 'raw_text',
        default    => '',
        page_panel => 'bmfsPublishInfo',
    },
);

sub new_fields { return @new_fields; }

This sets up the definition for fields named comment2 (our “secondary content” field) and comments (our “edit history” field). comment2 is a rich_text_brief field, and comments is raw_text (Big Medium’s data types are outside of the scope of this tutorial, but if you would like to know more, you can check out the Elements.pm file located at moxiebin/Modules/BigMed/Elements.pm).

We’ve also instructed Big Medium to add content2 to the bmfsPageContent (“Page Content”) panel in the edit screen. comments, meanwhile, will be added to bmfsPublishInfo (“Publication Info”). More on what that means in a sec.

With this initial code, we’ve set up the definition of the new data fields, but we still have to store them in the page data definition. By the time the plugin loads, Big Medium will already have the default data definition in place. So we can just piggyback on that, appending our new fields to the existing definition.

That’s what the following code does. The code should remain the same even if you change the fields that you’re adding; it simply takes the fields that we defined above and adds them to Big Medium’s existing page definition:

#extract the page-specific data fields (i.e. those that are not
#shared by all content types, including announcements and tips)

my %in_content = map { $_ => 1 } BigMed::Content->data_columns;
my %page_props = BigMed::Content::Page->properties;
my @page_cols  =
  grep { !$in_content{$_} } BigMed::Content::Page->data_columns;
my @elements;
foreach my $col (@page_cols) {
    push @elements, { %{ $page_props{$col} }, name => $col };
}

#elements now include the page-only data fields. Add our new
#fields, and store the revised definition
push @elements, @new_fields;
BigMed::Content::Page->set_schema( elements => \@elements, );

Add the fields to the edit screen

So far, we’ve told Big Medium how to save and retrieve data in the new fields, but we still need to teach it how to display those fields in the edit screen.

Our plugin will do this by overriding the built-in editor_fields routine and adding our fields to the default list of edit fields. Here again, the code that does this can remain as-is even if you change the fields that we defined above.

The code works by inserting our fields into the panels corresponding to the page_panel entry for each new field. We used bmfsPageContent and bmfsPublishInfo, but here’s the complete list of IDs for the available edit panels:

  • “Page Content” panel: bmfsPageContent
  • “About the Page” panel: bmfsAboutPage
  • “Page Preferences” panel: bmfsPagePrefs
  • “For Search Engines” panel: bmfsSearchEngine
  • “Publication Info” panel: bmfsPublishInfo

Here’s the resulting code:

package BigMed::Content::Page;
use strict;
use warnings;

sub editor_fields {
    my $self           = shift;

    #get the default edit fieldsets
    my @fieldsets = $self->SUPER::editor_fields(@_);

    #organize our new fields by fieldset panels
    my %fs_add;
    foreach my $f ( BMplugin::AddFields->new_fields() ) {
        push @{ $fs_add{ $f->{page_panel} } }, $f->{name};
    }

    #step through all of the default fieldsets and add the new
    #fields to the appropriate panels
    foreach my $fs (@fieldsets) {
        my $rcols = $fs_add{ $fs->{id} } or next;
        push @{ $fs->{fields} }, map { {
            column => $_,
            description => 'BM_PLUGIN_' . $_ . '_desc',
            }
        } @{ $rcols };
    }

    return @fieldsets;
}

Teach Big Medium some vocabulary

Finally, we just need to tell Big Medium how to label these new fields. We’ll give each field a title and a description like so:

my %language = (

    #title and description of secondary content
    'page:content2'           => 'Secondary Content',
    'BM_PLUGIN_content2_desc' =>
      'Supplementary content to appear on the page',

    #title and description of comment field
    'page:comments'           => 'Edit History',
    'BM_PLUGIN_comments_desc' =>
      'Editor comments; only other editors will see these',
);

#store these language definitions
my $nat = BigMed->bigmed->env('LANGUAGE') || 'en-US';
my $lang = BigMed::Language->get_handle($nat);
$lang->customize_lang(%language);

And that takes care of defining our fields and adding them to the edit screen.

Displaying the fields on pages

With the above code in place, Big Medium now knows how to save, retrieve and edit your new data fields. All that’s left is to teach it how to display those fields on your new pages. The add-widget.pm file does this by registering a new widget. In this example, we’ll create a <%content2%> widget to display the new “secondary content” field.

Big Medium’s format classes are responsible for building the various HTML, JavaScript, RSS and sitemap files that compose your site. These format classes each have their own add_widget method to add new widgets. This code adds a simple widget that displays the contents of the page’s content2 data field:

package BigMed::Format::HTML;
use strict;
use warnings;
my $HTML = 'BigMed::Format::HTML';

#add new widget for HTML pages
$HTML->add_widget(
    name    => 'content2',
    handler => \&wi_content2,
);

sub wi_content2 {
    my ( $context, $obj, $rparam ) = @_;
    my $text = $HTML->inline_rich_text( $obj->content2, $context );
    return $context->build_markup(
        'wi_content.tmpl',
        content => $text,
        class   => 'bmw_pageContent',
    );
}

1;
__END__

With the new widget added, you can now display the “secondary content” field on any page by including the <%content2%> widget in the template for the appropriate page type (“Layout > Edit Templates” in the Big Medium control panel).

Installing the plugin

After downloading and unzipping the plugin package, follow these steps to configure and install the plugin package.

Plugin: Add New Fields (5 KB)
Download the plugin files.

If you would like to customize the data field definitions to be different than the “secondary content” and “edit history” fields described above, follow these steps:

  1. Open add-fields.pm in a text editor.

  2. The file contains comments that call out the areas of the code to edit:

    • Make any changes to the field definition(s) in step one.
    • Make any changes to the field titles/descriptions in step two.
  3. If you would like to customize the content2 widget routine, open add-widget.pm in a text editor and make your changes.

After making your customizations (if any), set your FTP client to “plain text” or “ascii” mode and upload all three files to the moxiebin/plugins directory on your server.

With the files in place, you should now see your new fields in Big Medium’s edit screen.

Download Big Medium
Try it free for 30 days, or buy to unlock.

A Better Place

“The App Store would be a better place if every app designer read Tapworthy.
—Juri Pakaste, developer

Tapworthy is far and away the best book on the subject.”
—Mike Rundle, iOS designer, Flyosity

Tapworthy is a great read for every iPhone app maker!”
—Sophia Teutschler, iPhone developer

More praise for Tapworthy