Developer's Guide for Creating Plugins for the Breeze Website Builder™

Explanation of Fields in Plugin Record

When preparing a plugin to go into the Breeze Website Builder™, it could be useful to use the worksheet to organize your field entries. One option is to download a worksheet here. The record fields are provided in this worksheet for your convenience. Note: This worksheet has a PHP extension because it can be somewhat useful to view it in an HTML editor in code view, but it could just as easily have been given a TXT extension. A better option is to download the Plugin SDK here. It has a tool for creating the plugin record as well editors for building your console modules, and a utility for packaging your plugin as a zip file when you are all done. This plugin SDK is actually a plugin into itself. To install it, just install it as a plugin into your installation of the Breeze Website Builder™. You will see the new Plugin SDK button under SITE MANAGEMENT.

The required fields are name, description, category, and one of the following: head_code, head_html, content_code, content_html, header_code, header_html, footer_code, footer_html, top_code, top_html, left_code, left_html, right_code, right_html, bottom_code or bottom_html. All other fields are optional or will default to the correct value when not specified. But you may use any or all of the other fields as desired. If you have a style sheet for your plugin, then you will need to specify style_sheet, style_sheet_description, class_sql and css_sql. If you have a backend console, you will need to specify console_path, console_link_text and AccessLevel. It is also highly recommended to specify language_folder, console_link_text_define and help_path, and create the supporting language definition file and help file.

id
Simply an id field for your plugin. It is an auto-increment field, so do not bother to assign anything to it.

name
This is the name of your plugin. This will be displayed in the dropdown list in the create page module. Note: The plugin names are unique. If you name your plugin the same name as an existing plugin, it could create a collision and not install. Check here for a list of plugins names that are already in use.

description
A description for your plugin. This is also displayed in the dropdown list in the create page module.

category
Category is used to group plugins for easy locating when creating a page or adding a plugin to a page. The available categories are found in the plugin_categories table. If you want to add a category to that table, you would do this by adding the appropriate SQL statements to the plugin_sql as described below. Be sure to use the default prefix such that it will either be used or replaced with the one defined in the config file upon plugin deployment, i.e. bwb_plugin_categories Note: the category Console Only will create a plugin that cannot be deployed via creating a page or installing into a page. Instead this plugin will be deployed immediately upon installation. It therefore cannot have any site style sheets associated withit. It can however have its own custom database tables.

parent
Parent plugin name. Used for grouping plugins in families that can deployed at one time. If not set, then parent/single assumed and no children will be searched for. If set to same as plugin name, then this plugin is a parent with children. If this field is different than plugin name, then this plugin is a child of the plugin with the name that is in this field.

default_page_name
If your plugin is used in a page this is the suggested page name for plugin.

page_name_suffix
Suffix to be added to page name for child plugin pages if plugin group is deployed simultaneously. In this case, child plugin pages inherit parent plugin name with suffix appended.

style_sheet
The name of your style sheet for your plugin. The extension .css will be added automatically. so do not include .css. The style sheet name will also be used to create the names of the classes and css tables. Use of all lowercase is recommended. i.e. if your style sheet name is my_plugin, your CSS file will be named my_plugin.css, your css class names will be stored in the my_plugin_classes table, and your styles will be stored in the my_plugin_css table. The mobile style sheet tables will also be created from this field. The mobile tables will be automatically named my_plugin_mobile_classes and my_plugin_mobile_css.

style_sheet_description
A description of your style sheet. This description is displayed in the dropdown list used to select the style sheet to edit in the Breeze Website Builder™ styles editor.

class_sql
This is the SQL that will be used to create your CSS class records. To build your class records, use Manage Style Sheets to create a new style sheet. Then use the class editor under Edit Style Sheets to create your classes. Then dump the site_classes table and remove all of the non-pertinent records for other style sheets that are not part of your plugin. Replace INSERT with REPLACE if you want your plugin to be offered in the Wizard to avoid key-field conflicts. (Note: the Plugin SDK has tools build in for doing this.) Here is an example of some SQL that could be stored in this field:

REPLACE INTO `bwb_site_classes` (`style_sheet`, `class`, `description`, `sort_order`, `subclass_sort_order`, `custom`) VALUES
('mail_form', '.events_div', 'Surrounding Event Grid Div', 10, 0, 0),
('mail_form', '.events_table', 'Event Table', 20, 0, 0),
.
.
.
('mail_form', '.calendar_hebrew_header', 'Calendar Hebrew Header Text', 230, 0, 0);

It is also highly recommended that you include mobile classes for your plugin.

css_sql
This is the SQL that will be used to create your CSS records.To build your CSS records, you will have created your new style sheet using Manage Style Sheets as mentioned for class_sql. Then use Edit Style Sheets to create your CSS. Then dump the site_css table and remove all of the non-pertinent records for other style sheets that are not part of your plugin. Replace INSERT with REPLACE if you want your plugin to be offered in the Wizard to avoid key-field conflicts. (Note: the Plugin SDK has tools build in for doing this.) Here is an example of some SQL that could be stored in this field:

REPLACE INTO `bwb_site_css` (`style_sheet`, `class`, `use_table_data`, `font`, `font_size`, `text_color`, `padding_top`, `padding_right`, `padding_bottom`, `padding_left`, `weight`, `italic`, `underline`, `overline`, `blink`, `linethrough`, `font_stretch`, `oblique`, `small_caps`, `no_text_decoration`, `shadow`, `shadow_color`, `shadow_x_offset`, `shadow_y_offset`, `shadow_blur`, `align`, `vertical_align`, `line_height`, `line_height_units`, `bkgd_color`, `bkgd_opacity`, `border`, `border_color`, `border_style`, `outline_style`, `border_collapse`, `border_sides`, `margin_top`, `margin_top_units`, `margin_top_auto`, `margin_right`, `margin_right_units`, `margin_right_auto`, `margin_left`, `margin_left_units`, `margin_left_auto`, `margin_bottom`, `margin_bottom_units`, `margin_bottom_auto`, `display`, `width`, `width_units`, `height`, `height_units`, `position`, `position_left`, `position_left_units`, `position_top`, `position_top_units`, `position_right`, `position_right_units`, `position_bottom`, `position_bottom_units`, `z_index`, `overflow`, `clip`, `clip_top`, `clip_top_units`, `clip_right`, `clip_right_units`, `clip_bottom`, `clip_bottom_units`, `clip_left`, `clip_left_units`, `background_image`, `background_attachment`, `background_repeat`, `background_position`, `background_position_x`, `background_position_y`, `background_position_units`, `list_style_type`, `list_style_position`, `list_style_image`, `float`, `white_space`, `table_layout`) VALUES
('mail_form', '.events_tr_head', 1, '-not selected-', -1, '#FFFFFF', -1, -1, -1, -1, '-not selected-', 0, 0, 0, 0, 0, '-not selected-', 0, 0, 0, 0, '-not set-', 0, 0, 0, '-not selected-', '-not selected-', -1, 0, '#3e51b7', -1, -1, '-not set-', '-not selected-', '-not selected-', '-not selected-', 15, -1000000, 0, 0, -1000000, 0, 0, -1000000, 0, 0, -1000000, 0, 0, '-not selected-', -1, 0, -1, 0, '-not selected-', -1000000, 0, -1000000, 0, -1000000, 0, -1000000, 0, -1000000, '-not selected-', '', -1, 0, -1, 0, -1, 0, -1, 0, '-not set-', '-not selected-', '-not selected-', '-not selected-', 0, 0, 0, '-not selected-', '-not selected-', '-not set-', '-not selected-', '-not selected-', '-not selected-'),
('mail_form', '.calendar_tr_head', 1, '-not selected-', -1, '#FFFFFF', -1, -1, -1, -1, '-not selected-', 0, 0, 0, 0, 0, '-not selected-', 0, 0, 0, 0, '-not set-', 0, 0, 0, '-not selected-', '-not selected-', -1, 0, '#3e51b7', -1, -1, '-not set-', '-not selected-', '-not selected-', '-not selected-', 15, -1000000, 0, 0, -1000000, 0, 0, -1000000, 0, 0, -1000000, 0, 0, '-not selected-', -1, 0, -1, 0, '-not selected-', -1000000, 0, -1000000, 0, -1000000, 0, -1000000, 0, -1000000, '-not selected-', '', -1, 0, -1, 0, -1, 0, -1, 0, '-not set-', '-not selected-', '-not selected-', '-not selected-', 0, 0, 0, '-not selected-', '-not selected-', '-not set-', '-not selected-', '-not selected-', '-not selected-'),
.
.
.
('mail_form', '.events_td a:visited', 1, '-not selected-', -1, '#442C8C', -1, -1, -1, -1, '-not selected-', 0, 0, 0, 0, 0, '-not selected-', 0, 0, 1, 0, '-not set-', 0, 0, 0, '-not selected-', '-not selected-', -1, 0, '-not set-', -1, -1, '-not set-', '-not selected-', '-not selected-', '-not selected-', 15, -1000000, 0, 0, -1000000, 0, 0, -1000000, 0, 0, -1000000, 0, 0, '-not selected-', -1, 0, -1, 0, '-not selected-', -1000000, 0, -1000000, 0, -1000000, 0, -1000000, 0, -1000000, '-not selected-', '', -1, 0, -1, 0, -1, 0, -1, 0, '-not set-', '-not selected-', '-not selected-', '-not selected-', 0, 0, 0, '-not selected-', '-not selected-', '-not set-', '-not selected-', '-not selected-', '-not selected-');

It is also highly recommended that you include mobile CSS for your plugin.

custom_css_sql
SQL dump of default custom CSS record, i.e. Record from site_custom_css table with name my_style_sheet. Can also include custom mobile styles, i.e. name of my_style_sheet_mobile.

head_code
This is the PHP code that is inserted into the head section of the page file. You can of course put HTML, Javascript, etc. it here as well, but any code inserted it here will NOT be editable in the Breeze Website Builder™. PHP stored in a MySQL record and retrieved via a PHP file for export to screen obviously will not run as PHP. Therefore it is necessary to have your PHP embedded right into the page file.

head_html
This is the HTML code that is inserted into the head content for the page. The Breeze Website Builder™ assumes that this head content is only useful for the page that has the plugin installed; therefore, it automatically creates an additional head-content record and assigns it to the newly created page that will have your plugin. You can of course put HTML, Javascript, etc. it here, but not PHP as this code is pushed to the client for processing. Any code inserted it here WILL be editable in the Breeze Website Builder™ by using the head code editor.

Special Note: To make adding JavaScript includes, style sheet links and so forth adaptable to however the user has the folders setup in the config file, the following strings will be replaced upon creating pages with plugins, or inserting a plugin into a page:
scripts/
css/
images/
media/
flash/
Therefore, use these default folders in this plugin field rather than any custom folders you may have configured.

header_code
This is the PHP code that is inserted into the very top of the body of the page. If you need to dynamically generate HTML or JavaScript at the top of the body, you would put your PHP code in here to do this.

header_html
This is the HTML code that is inserted into the very top of the body of the page. If you want to provide HTML that precedes content in the page top, add your HTML here. This HTML will appear inside of a div with an ID of header and a class of header. Note: The width of this div could be different than that of the wrap div, for instance across the top of the entire browser window.

top_code
This is the PHP code that is inserted into the top of the page inside the wrap div. If there is header content, the header will be above the top. Otherwise the top will appear at the very top of the page. If you need to dynamically generate HTML or JavaScript at the top of the page inside the wrap div, you would put your PHP code in here to do this.

top_html
This is the HTML code that is inserted into the top of the page inside the wrap div. If there is header content, the header will be above the top. Otherwise the top will appear at the very top of the page. If you want to provide HTML content at that top and inside the wrap div, add your HTML here.

left_code
This is the PHP code that is inserted into the left of the page inside the wrap div. If you need to dynamically generate HTML or JavaScript at the left of the page inside the wrap div, you would put your PHP code in here to do this.

left_html
This is the HTML code that is inserted into the left of the page inside the wrap div. If you want to provide HTML content at that left and inside the wrap div, add your HTML here.

content_code
This is the PHP code that is inserted into the body section of the page file. You can of course put HTML, Javascript, etc. it here as well, but any code inserted it here will NOT be editable in the Breeze Website Builder™. PHP stored in a MySQL record and retrieved via a PHP file for export to screen obviously will not run as PHP. Therefore it is necessary to have your PHP embedded right into the page file. Any content entered for a page with a plugin is displayed before the plugin code. A webmaster using the Breeze Website Builder™ could use the reserved string divider <!-- Page Content Divider --> get any part or all of their content to display after the plugin.

content_html
This is the HTML code that is inserted into the body content for the page. You can of course put HTML, Javascript, etc. it here, but not PHP as this code is pushed to the client for processing. Any code inserted it here WILL be editable in the Breeze Website Builder™ by using the head code editor.

right_code
This is the PHP code that is inserted into the right of the page inside the wrap div. If you need to dynamically generate HTML or JavaScript at the right of the page inside the wrap div, you would put your PHP code in here to do this.

right_html
This is the HTML code that is inserted into the right of the page inside the wrap div. If you want to provide HTML content at that right and inside the wrap div, add your HTML here.

bottom_code
This is the PHP code that is inserted into the bottom of the page inside the wrap div. If there is footer content, the footer will be below the bottom. Otherwise the bottom will appear at the very bottom of the page. If you need to dynamically generate HTML or JavaScript at the bottom of the page inside the wrap div, you would put your PHP code in here to do this.

bottom_html
This is the HTML code that is inserted into the bottom of the page inside the wrap div. If there is footer content, the footer will be below the bottom. Otherwise the bottom will appear at the very bottom of the page. If you want to provide HTML content at that bottom and inside the wrap div, add your HTML here.

footer_code
This is the PHP code that is inserted into the bottom of the body of the page just above the footer_html in the footer div. If you need to dynamically generate HTML or JavaScript at the bottom of the body, you would put your PHP code in here to do this.

footer_html
This is the HTML code that is inserted into the very bottom of the body of the page. If you want to provide HTML that follows content in the page bottom, add your HTML here. This HTML will appear inside of a div with an ID of footer and a class of footer. Note: The width of this div could be different than that of the wrap div, for instance across the bottom of the entire browser window. This footer div is handy for placing content that sits on the bottom of the browser window independent of the content height. Simply set the style of the div with display of block and a position of bottom=0.

console_path
This is the path to a backend console module that you created to FTP to the site. A button will appear in the main menu of the Breeze Website Builder™ when somebody creates a page with your plugin in it. You can put it in any folder you wish. Make the path absolute with regard to webroot, i.e. /plugins/my_plugin_console.php

console_link_text
This is simply the text you want to show on the button for accessing your backend console to your plugin.

console_link_image
This the path to the image that will be used for the plugin console button normal state.

console_link_image_mo
This the path to the image that will be used for the plugin console button mouse-over (hover) state.

console_link_image_down
This the path to the image that will be used for the plugin console button down state.

help_path
This is the path to the help topic for this plugin. You could host your own help topic and put the URL to that page here, or you could have that topic hosted at http://breezewebsitebuilder.com/docs/cms/help.html#yourhelptopic upon request.

language_folder
Folder name to store language Files. Typical path is manage/plugins/lang/yourpluginname and is relative to document root.

console_link_text_define
Name of language define for console link test in language files. If a language file is provided, this will be used instead of console_link_text.

button_group
Group or editor to include console button. For main-menu buttons, possible values are content_functions (CONTENT), menu_functions (MENUS), style_functions (STYLES & HEAD CONTENT), page_functions (PAGE MANAGEMENT) and other_functions (SITE MANAGEMENT). If left blank, button group will default to other_functions. For editors, possible values are all_editors (All Editors), design_view_editors (Design View Editors), code_view_only_editors (Code View Only Editors), head_code_editor (Head Code Editor), css_editor (CSS Editor) and file_editor (File Editor). design_view_editors are Page Editor and Border Area Editor. code_view_only_editors are Head Code editor, Custom CSS Editor, and File Editor.

plugin_sql
If the backend console of your plugin uses database tables, you can dump the initial configurations of your tables and put the SQL to recreated them hear. If your plugin has not yet been deployed, then when the webmaster creates a page using your plugin, the Breeze Website Builder™ will run this SQL to setup your plugin tables. You may also add fields or records to built-in Breeze Website Builder™ tables. If doing so, just be sure to prefix the tables in your SQL with bwb_ such that SQL parser can substitute the correct table prefix per the config file.

AccessLevel
Access level required to have access to your backend console. If the logged-in user does not have sufficient privileges to use your plugin, then they will not see your plugin button on the main menu.

deployed (moved to plugins_deployed table)
This is a flag that tells that Breeze Website Builder™ whether or not your plugin is in use on the website. 0 = not in use, 1 = in use. Set it to 0 initially.

available
This provides a way to add or remove plugins from the offering on any particular website. When set to 1, the plugin will show up in the dropdown list box in the Breeze Website Builder™ create-page module. When set to 0, the plugin will not be listed there. You will of course want to set this to 1. This featured is provided to allow administrators to prune the offerings for what ever reason.

disable_site_styles
Flag to turn off import of site styles when editing. (0 = styles used, 1 = no styles used) Pages used strictly for created HTML email messages are typically set to not use site styles as the styles will need to be embedded in the message.

body_onload, body_onload_function
Flag to determine if plugin includes function call upon body_onload event. (0 = no, 1 = yes) If set, then the fuction defined in body_onload_function will be called after the page fishises loading. By default, the name of the function is xxx_load(); where xxx is the name of the page, but you may specify the name of the function you created in the body_onload_function field.

sort_order
Order in which your plugin will appear in the dropdown list on the Breeze Website Builder™ create-page console. You will want to look at the existing plugins to find out what there sort order numbers are.

 

Explanation of Rapid Development Buttons in Plugin SDK Record Manager

add style sheet

The Add Style Sheet button will use the name and description you typed in for your plugin CSS style sheets to create a new style sheet it the system. Once the style sheet is created, you may edit your styles using the CSS and class editors.

get style sheets and classes button

Clicking the Get Style Sheet Classes, CSS and custom CSS SQL will dump the SQL from the classes, CSS and custom CSS tables per the style sheet you defined above. Perform this step after you are done setting up your styles, or if you have upgrade your styles for the plugin. You must click Save to record your plugin CSS SQL as part of the plugin record.

get code and put code buttons

The Get Code button becomes active after selecting the file that contains your plugin PHP code from the dropdown list. To edit your plugin code, use the file editor to create a file in the web page folder along side the web page files. Then select your file from the list and click the Get Code button to put the contents of the file into the box labeled Head Code, Header Code, Top Code, Left Code, Content Code, Right Code, Bottom Code or Footer Code depending on what row the button is in. You must click Save to record your plugin code as part of the plugin record.

The Put Code button allows you to insert your plugin code into an actual page file for testing. Select a test page from the list and click the Put Code button, and your plugin code will be inserted into the test page as Head Code, Header Code, Top Code, Left Code, Content Code, Right Code, Bottom Code or Footer Code depending on what row the button is in. You must click Save to record your plugin code as part of the plugin record.

get HTML button

You can develop plugin HTML and/or JavaScript as content, or in any of the border areas or head by using the appropriate Breeze Website Builder editor. When you are done with your HTML/JavaScript (or after updating it) you may click the Get HTML button in the corresponding row to place the HTML/JavaScript into your plugin record. You must click Save to record your plugin code as part of the plugin record.