Carrington Build Documentation

The Admin Form

The admin_form() method is used to collect user settings and content for each module. The admin_form() method must return HTML. The module admin form only needs to contain the form fields you need to collect. Do not include the form tags as those are automatically added to the output.

Like WordPress Widgets there are helper methods to help keep your field names and IDs name-spaced. The following is an example of a basic admin interface that gathers title and content data from the user:

Any fields included in the admin for that are not disabled (ie: disabled=”disabled”) will be submitted and passed through the update() method before being saved. If there are auxillary fields in the markup that shouldn’t be saved in to the database or if some data transformations should be done use the update() method to modify $data before it is saved. For example:

The View File

Carrington Build’s default Modules all use the combination of a view.php file and the load_view() method to provide some separation between the module logic and the module display. The default location for the view.php file is the root level of your module’s folder. View’s are loaded in an output-buffer so while it is required that Modules return html this allows the use of functions that echo.

While using load_view() is recommended, it is not mandatory. The base requirement is that your display() method return HTML.

Loading the View

To use the load view function pass $data as the first parameter and optionally supply a key => value array of extra parameters that you want to pass in to the view. Anything passed in via the 2nd parameter will be extracted in to the local scope for the view. So, below, $my_param will be made available in the view.

Overriding the View

By default the load_view() method will look for a view.php in your module’s folder. If it finds none it will return null. In some situations it may make sense to alter the view file based on some parameter (like, maybe your front page needs a slightly different output template). In this case use the included filter to change the module’s view file before it is loaded.

The view can be filtered on a per module basis using cfct-module-module-id-admin-view. Replace module-id with the id of the target module. In your function you need to return the full path to the view file to override the default. $data is passed to the filter as well so views can also be filtered based on the content of the module.

An example of overriding the Callout module’s view for the home page:

Providing Multiple Views

The view loading mechanism also allows for custom view files to be defined by the module itself. Lets say, for example, that you want to provide different layouts to your module as a selectable preference. Provide the user with a way to select the view template to use and then change the $this->view property of the module before calling load_view().

Custom JavaScript

Modules can provide additional functionality for both the admin and front end displays by overriding the admin_js() and js() methods. Carrington Build uses a [jQuery](http://docs.jquery.org, “jQuery Documentation”) wrapper with $ enclosed in a local scope. This may be incompatible with your preferred JavaScript library. There are no plans at this time to officially support other libraries besides jQuery.

Client side JavaScript is straight forward. Add a js() method to your module, return the Javascript to be included and it will be included in the front end output.

JavaScript for the Admin requires a bit more attention. Since the modules are loaded in via Ajax

Admin JS Module Load Callbacks

Because modules are loaded via Ajax the typical DOM Ready methods are not relevant. For this purpose Carrington Build provides the ability to add Module Load Callbacks. You are not limited to a single callback function, so if your module extends another module you don’t have to replicate its JavaScript, just include your JavaScript along with it. Any JavaScript actions can be performed within the module including show/hide actions, click events, and Ajax calls. An example of using the Module Load Callback framework:

Admin JS Module Save Callbacks

Carrington Build also provides a callback at Module Save so that the form data can be pre-compiled, cleaned up, or checked for requirements before the form is submitted. Adding a Module Save Callback is similar to the Module Load Callback except that the return value of the function affects whether the module form will submit or not. Returning true allows the module save action to continue, returning false aborts the click action on the module save and the module form will not submit and the module edit window will stay open.

When Extending Other Modules

When extending an existing module you probably also want to include its JavaScript as well. If you don’t need to modify the JavaScript or add any new JavaScript you simply do nothing. The parent module’s admin_js() method will be called and included.

If you need to add to the Javascript create an admin_js() method that defines all of your required Javascript and also includes the parent class’ admin_js(). If the parent class’ Javascript was properly name-spaced then your module’s $id_base will be used when including the Javascript to avoid conflicts. For example:

Custom CSS

CSS inclusion, like JS inclusion, is separated in to distinct front end and admin methods. To add client side CSS create a css() method and return the necessary style declarations. To add Admin styling add an admin_css() method and return the necessary styling elements. An example of Admin CSS:

Suppressing Module Save

Modules can define wether they can be saved or not. If, for example, your module should only be modified by editors and higher, then you can use the $suppress_save member variable to control the appearance of the save button in the module admin. For example:

Controlling Module Availability

If you only want your module to display under certain conditions you can override list_admin() method to control the module’s availability in the edit screen. Returning false from the list_admin() method will prevent the module from appearing in the module selection dialog. For example:

This does not prevent a module that is used in a layout from displaying in the layout. It simply prevents the addition of new modules of that type.

Module Options

Carrington Build contains a framework for creating Module Options that are added to every module’s Edit Screen under the “cog” menu. The default Module Option is a Module Classes option that allows each module to be given additional classes on its wrapping </div>.

Module Helper Methods

These remain mostly undocumented for now, but the examination of carrington-build/classes/module-utility.php will reveal many helper functions that you as a developer can take advantage of.

Advanced Development - Creating Custom Build Rows

Carrington Build Rows are customizable in much the same way that Modules are.

Rows Directory Structure

Rows are loaded in the same manner as Modules are loaded. The loading process is based on the parent Rows directory containing folders of rows.

Defining Row Load Directories

Carrington Build loads rows by scanning directories for compatible file structures much like WordPress loads Plugins by scanning the Plugins directory. To define a row load directory add a function that runs on the cfct-row-dirs filter. For example, to add a modules directory in your theme directory use the code:

Custom CSS

Rows can provide custom CSS for both the admin and front end outputs. Create a css() method to return client side CSS or an admin_css() method to return admin CSS. These methods are called automatically by Build and the returned CSS is added to the CSS delivered by Build.

See the Custom CSS section of the “Creating Modules” documentation (above) for examples of how to return custom CSS.

The Row File

The main row file is where the row should be defined and registered with Carrington Build. The minimum requirements for a row to work is the __construct() method. The constructor is where everything the row needs is defined via the $config array.

The icon location is defined in the constructor of the row. When registering your row’s options point to the row location relative to the location of the row’s include directory when defining the icon.

Config Variables

name: A friendly name for the row. Appears under the row icon in the row chooser on hover.
description: A friendly description for the row. Appears in a tool-tip in the row chooser on hover.
icon: location of the icon file for the row. This follows the same convention as module icons with module-folder-name/icon-file.ext. If left empty or not included a default icon will be used.
class: the classname for the outer row wrapper. This is also used for internal identification purposes and should be unique.
html: custom front end HTML output for the row. By default Build wraps the row’s blocks and modules in a simple div wrapper.
admin_blocks: custom admin layout for the row. By default Build wraps each block in a table cell and auto associates the block controls with the block. Use this field to provide a custom inner table structure for the layout of the admin row display.
blocks: an array of details about how blocks should be constructed inside admin rows. There should be an entry for each block that the row supports.

class: class name(s) to be applied to the table cell for the block.

attrs: attributes to be applied to the table cell for the block.

html: custom front end HTML output for each module that will appear in the block.

See the included “Stacked” row type in carrington-build/rows/stacked/ for an example of how all these variables can be used to create a custom, complex row.

Advanced Development - Customizing Carrington Build Modules

Carrington Build ships with many included filters that allow for the modification of Build data at many points during both the input and output of data.

Carrington Build Core Filters

Change Carrington Build’s Path or URL

cfct-build-loc: Returns an array of Build’s determined URL & Path values. Alter these to run Build out of a non-standard location. Standard (ie: supported) locations include: the main or child theme folder, the plugins directory, the mu-plugins directory. Build is not officially supported outside of these directories so use caution as Build may not function properly in your chosen location.

Change Default Classes for Content Styles

cfct-class-groups: Carrington Build supplies some default classes for defining content output options in some modules (ie: callout, post-callout) for size of headers and content as well as image alignment. The defaults for these options can be modified to support a custom naming scheme or can be extended as necessary to fit the project at hand.

Modify list of Widgets in Module Select List

cfct-modern-widgets: Carrington Build automatically enables all “modern” (ie: object style widgets) as Carrington Build modules for use in Build layouts. Use this filter to modify the list of widgets that will be included as Carrington Build modules.

Add a Module Load Directory

cfct-mdoule-dirs: Carrington Build loads modules on a per directory basis, not a per module basis. Use this filter to register a new location for Carrington Build to load modules from. See the “Modules Directory Structure” section of the “Creating Modules” documentation for more information.

Add a Module-Options Load Directory

cfct-module-options-dirs: Carrington Build loads module-options in the same way that it loads modules. Use this filter to add additional module-options load directories.

Add a Row Load Directory

cfct-row-dirs: Carrington Build loads Rows in the same way that it loads modules. Use this filter to add additional row load directories. See the documentation on “Creating Rows” for more information on Build rows.

Modify Build Default Data Structure

cfct-default-data: Use this filter to add some additional default data to modules when they are created. Unexpected results may occur from removing any of the default data items.

Modify a Post’s Data from the Database

cfct-get-postmeta: Use this filter to inspect or modify an entire post’s build data before it is acted upon. This filter is used on both the front end output and in the admin screens.

Row Filters

Modify Row Default Class Names

cfct-row-defaults: Allows for the modification of default front end row & block class names. Admin row & block class names cannot be modified.

Modify a Row’s HTML Output

cfct-build-row-{$row_class}-html: Modify the row’s compiled HTML before it is merged for front-end output.

Modify a Row’s HTML Wrapper

cfct-row-html: Modify the wrapper HTML used for row output before it is merged with the module content. See the documentation on “Creating Rows” for more information on how to manage the row wrapper HTML.

Modify a Row’s Block Wrapper

cfct-block-html: Modify the wrapper HTML used for block output before it is merged in with the row. See the documentation on “Creating Rows” for more information on how to manage the row wrapper HTML.

Modify a Row’s Chooser Icon

cfct-{$row_class}-row-icon: Modify the URL to the row’s icon file.

Output Filters & Actions

Modify or Inspect the Build Object at Output

cfct-build-pre-build/cfct-build-post-build: Use these actions to modify or inspect the Carrington Build object before/after the output HTML is built.

Modify the Build Output Before it is Rendered

cfct-build-content: Use this filter to modify the Build HTML output before it is passed on to WordPress.

Modify the Build CSS or JavaScript

cfct-build-css/cfct-build-js: Modify the front end CSS or Javascript after it is compiled for delivery to the browser.

cfct-module-extras: Modify the front end or admin CSS or JavaScript after its compiled for delivery to the browser. Passed arguments allow for determination of Javascript vs. CSS and front end vs. admin.

Admin Filters & Actions

Active Carrington Build on Other Post Types

cfct-build-enable-post-types: By default Carrington Build is enabled only on pages. To enable Carrington Build on other post types use this filter to add other post types to the enabled types array.

Modify Build Before Admin Display

cfct-admin-pre-build: Modify the Build object before the Admin Interface is displayed.

Modify the Default Page Title for Build Pages

cfct-autosave-title: Carrington Build will force an autosave if a Build layout is started on a new post/page. Use this filter to change the default title given to autosaved posts/pages.

Modify Saved Post Content

cfct-pre-save-post: Carrington Build saves a stripped down version of the module content in the $post->post_content field for search purposes. This filter enables the modification of that content. Note that since Carrington Build saves each module’s content individually the post’s content is also updated on each save.

Modify the Postmeta Key for Build Data

cfct-build-postmeta-key: The default value for the Build postmeta key is _cfct_build_data. Use this filter to modify that key. Changing this value with existing Build data will orphan that data, but not destroy it.

Modify Page Options Menu

cfct-build-page-options: Carrington Build provides a page options menu under the cog icon. The cog icon shows only when there’s a build layout. It appears inline with the Build tab. This filter allows for adding items to the page options menu.

Module Filters

Modify a Module’s Class Name(s)

cfct-build-module-class: By default a module’s wrapper div is output with 2 class names, cfct-module and the $id_base of the module. Use this filter to modify the wrapper div’s class output on a per-module basis. Each individual module in a layout will fire this filter on front end output.

Modify a Module’s HTML Output

cfct-module-{$module-id}-html: Each individual module’s HTML output can be filtered here. This is the last filter available before the Module is rendered in the page and consists of all pre-rendered HTML.

Modify a Module’s View File

cfct-module-{$module_id}-view: Override the module’s view.php file. Provide a full file path to a view file to load. See “The View File” section of the Creating Modules documentation for more details on this filter.

Modify a Module’s Admin Form HTML Output

cfct-module-{$module_id}-admin-form: Each module’s Admin Form HTML can be filtered here. This is the last filter available before a module’s Admin Form is wrapped in the Module Edit HTML.

cfct-module-{$module_id}-admin: Modify the complete Module Edit screen HTML before it is sent back over Ajax.

Modify the Module’s Text output

cfct-module-{$module_id}-text: Modules should return a plain text representation of their data to be inserted in to the post_content for search and accessibility purposes (WordPress will still make excerpts from the post_content). This filter allows access to the plain text representation of a module before it is saved in to the post_content. By default, too, the Admin text is pulled from this as well.

Modify a Module’s Icon File URL

cfct-{$module_id}-module-icon: Each module, whether it supplies an icon or uses the default icon, is asked for the url to its icon when the admin screen is rendered. Use this filter to change the URL to the icon to customize a module’s icon.

Modify a Module’s Data When Saved

cfct-module-{$module_id}-update: Use this filter to inspect or modify a specific module’s save data before that data is saved.

Modify a Module’s URL or Filesystem Path

cfct-module-{$module_id}-url/cfct-module-{$module_id}-path: The base module class provides helper methods of get_url() and get_path() to assist modules that need to load or enqueue additional resources (like javascript or images). This filter allows access to that url to override or customize those resources without modifying to module itself. The module has already been constructed by the time this gets run.

cfct-build-module-url: Alter the module’s URL at module load time. This gets run at module construct.

cfct-build-module-url-unknown: If for some reason the URL to the module cannot be determined it will be passed through this filter before it is recorded by build.

cfct-build-module-urls: Carrington Build keeps a list of module URLs that from which the modules can pull their URL. Use this filter to modify the list as a while. This is run after cfct-build-module-url & cfct-build-module-url-unknown.