Reusable Components

The main Barebones CMS editor is designed in such a way that the major pieces that you interact with in the editor can also be used in Widgets and Shortcodes and even used on the frontend (what users see). Most of the third-party tools in the Barebones CMS have been wrapped up either in the Global Functions or an easy-to-use Javascript file.

This documentation covers all of the reusable Javascript-based components of the Barebones CMS.

Conversion Functions: 'support/convert.js'

These conversion functions are mostly designed to support the progress bar and upload manager Javascript files. However, they can be useful for other things as well.

ConvertIntCharToHex(num)

Parameters:

Returns: A string containing the integer converted to hexadecimal.

This function takes an integer and converts it to hex. There is no error checking.

ConvertRGBToHex(red, green, blue)

Parameters:

Returns: A string containing each color converted to hex.

This function caps the values of red, green, and blue to 0 to 255 inclusive and then converts the integers to hex with ConvertIntCharToHex(). The returned string does not include a '#' prefix.

ConvertHSBToRGB(hue, saturation, brightness)

Parameters:

Returns: An array containing [red, green, blue] integers.

This function takes a HSB triplet and converts it into a RGB triplet. Designed to be a fairly Photoshop-like conversion - output is similar but not always exactly the same.

ConvertIntToFriendlyNum(num)

Parameters:

Returns: A string with the integer comma-separated at the thousands position.

This function is a U.S. English-only converter for numeric values for display to the user. It takes an integer and inserts a comma every three characters.

ConvertBytesToFriendlyLimit(num)

Parameters:

Returns: A string containing 'num' in a user-friendly format.

This function returns 'num' bytes in KB, MB, or GB format - whichever makes sense. Also shows one or two places past the decimal depending on the amount leftover from conversion to the best possible format.

ConvertSecondsElapsedToFriendlyLimit(num)

Parameters:

Returns: A string containing 'num' in a user-friendly format.

This function is a U.S. English-only converter for taking the number of seconds elapsed and returning a string with days, hours, minutes, and seconds.

Progress Bar Functions: 'support/progress.js'

These functions create, display, and manage a colored progress bar. Primarily used within the Barebones CMS for file uploads. This file requires jQuery to function properly.

CreateProgressBar(id)

Parameters:

Returns: Nothing.

This function sets up the progress bar 'div's.

UpdateProgressBar(id, percent, color)

Parameters:

Returns: Nothing.

This function updates an existing progress bar that was created with CreateProgressBar(id) with a new percentage and color. Allows for the color to change as the progress bar moves.

ResetProgressBar(id)

Parameters:

Returns: Nothing.

This function resets the progress bar to 0%.

ConvertProgressBarPercentToColor(percent, colorinfo)

Parameters:

Returns: An array containing calculated [Hue, Saturation, Brightness] values.

Example from the reusable file upload component:

ConvertProgressBarPercentToColor(52, {
	first : [1, 100, 60],
	last : [83, 100, 84],
	ranges : {
		10 : [1, 100, 84],
		35 : [25, 100, 84],
		60 : [57, 100, 84],
		90 : [83, 100, 84]
	}
});

This function takes a percentage and determines the exact HSB color in a gradient specified by 'colorinfo'. Designed for smooth color changes as a progress bar moves along.

Status Updater Functions: 'support/status.js'

These functions create, display, and manage a status information box with optional progress bars. Primarily used within the Barebones CMS for handling file upload progress and results. This file requires jQuery to function properly.

CreateStatusUpdater(id, opts)

Parameters:

Returns: A boolean of true.

Example from the reusable file upload component:

CreateStatusUpdater(id, {
	progressbars : [
		{
			first : [1, 100, 60],
			last : [83, 100, 84],
			ranges : {
				10 : [1, 100, 84],
				35 : [25, 100, 84],
				60 : [57, 100, 84],
				90 : [83, 100, 84]
			}
		},
		{
			first : [1, 100, 60],
			last : [83, 100, 84],
			ranges : {
				10 : [1, 100, 84],
				35 : [25, 100, 84],
				60 : [57, 100, 84],
				90 : [83, 100, 84]
			}
		}
	],
	useinfo : true,
	usemessages : true
});

This function creates a status updater area out of an empty 'div'. The update area can contain one or more 'progressbar's, an information area ('useinfo'), and an expandable message area ('usemessages').

DestroyStatusUpdater(id)

Parameters:

Returns: Nothing.

This function cleans up internal object memory related to a status updater and removes the injected HTML that was added by the CreateStatusUpdater() function.

ShowStatusUpdaterProgressBar(id, num, show, resetbar)

Parameters:

Returns: A boolean of true if the progress bar was successfully updated, false otherwise.

This function affects the display status of a progress bar created by the CreateStatusUpdater() function.

SetStatusUpdaterProgressBar(id, num, percent, data)

Parameters:

Returns: A boolean of true if the progress bar was successfully updated, false otherwise.

This function moves the position and color of the progress bar and updates information below it. The progress bar must have been created with the CreateStatusUpdater() function.

SetStatusUpdaterInfo(id, data)

Parameters:

Returns: A boolean of true if the information area was successfully updated, false otherwise.

This function displays status information or just injects HTML into a 'div' below the progress bars (if any). The reusable upload component uses this function to inject a SWFUpload placeholder 'div'.

AddStatusUpdaterMessage(id, message, msgtype, msgtypeplural)

Parameters:

Returns: A boolean of true if the message was successfully added to the queue, false otherwise.

This function adds a message to the message queue and displays the output. If there is one message of msgtype, then msgtype is displayed, otherwise msgtypeplural. For example, if there are two 'Warning' messages and one 'Error' message, the displayed output could say, "2 Warnings, 1 Error".

File Upload Functions: 'support/upload.js'

These functions create, display, and manage a file upload button (SWFUpload), progress bar(s), and information areas. Primarily used within the Barebones CMS for handling file uploads. This file requires jQuery to function properly. Note that SWFUpload is designed for AJAX style uploading, which is different from most 'form'-based uploaders. The target script must be capable of handling this.

Note that many of the functions in 'upload.js' are "undocumented" - they all start with the prefix "SWFUI_". These are support functions that allow SWFUpload to work properly. They are callbacks performed by SWFUpload, which has documentation on what each callback is for. This is laziness at its finest!

CreateSWFUploadInterface(id, ...)

Parameters:

Returns: A SWFUpload object.

This function creates a SWFUpload interface wrapped up with placeholders for two progress bars and a message area for results. When the user clicks the button, the standard file selection dialog appears. Once files are selected and the dialog closes, the file upload begins. During the file upload, one or two colored progress bars appear to track progress of the upload.

When inside the main Barebones CMS editor, Shortcodes should use the $parent->CreateShortcodeUploader() call, which creates a standard file transfer dialog. Widgets should not need to upload files since File Explorer is usually used for that. In the event this function does need to be called, 'callback' should be 'ManageFileUploadResults' (without quotes) and both 'params' and 'callbackparams' should be the output of BB_CreatePropertiesJS() or equivalent calls.

Note that SWFUpload has several bugs, the most severe bug being unable to pass cookies correctly. This limitation is overcome by calling the ProcessAllInput() function in 'proc.php', which allows $_GET and $_POST to override cookies in $_REQUEST. The solution is to pass cookies via the 'params' option. See examples in the main Barebones CMS editor source code - the $usebbl parameter in BB_CreatePropertiesJS() gets set to 'true'.

This function may be rewritten in the future to simplify the function call to offer more flexibility.

DestroySWFUploadInstance(swfu)

Parameters:

Returns: Nothing.

This function safely removes a SWFUpload interface and its surrounding wrapper that was created with CreateSWFUploadInterface(). If a SWFUpload interface is removed from a page by removing the HTML without calling this function first, a Javascript error will occur.

File Editor Functions: 'support/editfile.js'

These functions are designed to create, manage, and edit files. This component creates a wrapper interface around ACE and EditArea to simplify the process of adding a file editor to the page. This file requires jQuery and jQuery UI to function properly.

Note that many functions in 'editfile.js' are "undocumented" - they all start with the prefix "EAUI_". These are support functions that introduce an AJAX-style layer to EditArea and wrap up the more difficult bits of logic into a clean interface. Only the documented functions are really necessary to know about to deploy this component. That, and I'm feeling both a bit lazy and documenting the functions would only clutter this documentation.

CreateEditAreaInstance(eid, fileopts, editopts)

Parameters:

Returns: A boolean of true if the ACE or EditArea object was successfully created or updated, false otherwise.

This function creates an ACE or EditArea instance or loads data into an existing instance. There are two modes: Single file and multiple files. The main Barebones CMS editor uses multiple file mode. Single file mode is intended for use in a frontend of some sort. However, since this is designed for editing code (PHP, Javascript, etc.), the Content Editor is usually the better option for frontend use.

Single file mode probably no longer works - if you really need this, file a bug report. When single file mode is used, the 'eid' parameter may also refer to a 'textarea' on the page where the 'id' is eid + '_edit'. The content of the 'textarea' is used by default in this case, so 'fileopts' does not need 'loadurl' or 'loadcontent' specified.

The 'fileopts' object contains information about the "file" to load into the EditArea instance:

The 'editopts' object contains information about the ACE/EditaArea instance itself:

When in multiple file mode, the 'editopts' object should be identical between calls for the same 'eid'.

DestroyEditAreaInstance(eid)

Parameters:

Returns: Nothing.

This function deletes an EditArea instance, the wrapper (if any), and cleans up internal memory objects.

Note: Under Firefox, this function is buggy. EditArea instances with the same 'eid' can't be created twice. Prefer calling HideEditAreaInstance() instead.

Note: Calling this function right away after the last file is closed in multiple file mode will result in a Javascript error. Put this function in a SetTimeout() callback function.

HideEditAreaInstance(eid)

Parameters:

Returns: Nothing.

This function hides the EditArea instance from the user. ShowEditAreaInstance() is automatically called when calling CreateEditAreaInstance() later on with the same 'eid'.

Note: Calling this function right away after the last file is closed in multiple file mode will result in a Javascript error. Put this function in a SetTimeout() callback function.

ShowEditAreaInstance(eid)

Parameters:

Returns: Nothing.

This function shows an existing EditArea instance that was hidden via HideEditAreaInstance().

Content Editor Functions: 'support/editcontent.js'

These functions are designed to create, manage, and edit content. This component creates a wrapper interface around WYMEditor to simplify the process of adding the content editor to a page. This file requires jQuery to function properly. The multi-content editor mode requires jQuery UI to function properly.

Note that many functions in 'editcontent.js' are "undocumented" - they all start with the prefix "WYMUI_". These are support functions that introduce an AJAX-style layer to WYMEditor and wrap up the more difficult bits of logic into a clean interface. Only the documented functions are really necessary to know about to deploy this component. That, and I'm feeling both a bit lazy and documenting the functions would only clutter this documentation.

CreateWYMEditorInstance(eid, fileopts, editopts)

Parameters:

Returns: A boolean of true if the WYMEditor was successfully created or updated, false otherwise.

This function creates an WYMEditor instance or loads data into an existing instance. There are two modes: Single content and multi-content editor. The main Barebones CMS editor used the multi-content editor mode. Single content mode is intended for use in a frontend of some sort.

When single content mode is used, the 'eid' parameter may also refer to a 'textarea' on the page where the 'id' is eid + '_edit'. The content of the 'textarea' is used by default in this case, so 'fileopts' does not need 'loadurl' or 'loadcontent' specified.

The 'fileopts' object contains information about the "file" or content to load into the WYMEditor instance:

The 'editopts' object contains information about the WYMEditor instance itself:

When in multi-content editor mode, this object should be identical between calls for the same instance.

DestroyWYMEditorInstance(eid)

Parameters:

Returns: Nothing.

This function deletes a WYMEditor instance, the wrapper (if any), and cleans up internal memory objects.

InsertWYMEditorContent(eid, id, content)

Parameters:

Returns: A boolean of true if the content was inserted successfully, false otherwise.

This function inserts content into an existing WYMEditor instance. The main Barebones CMS editor uses this to insert Shortcode placeholders.

© CubicleSoft