The First-Time Users documentation briefly covered the Code widget in the Barebones CMS. This documentation covers everything about the Code widget that you will likely ever need to know.
In terms of code complexity, the Code widget is the simplest of the three default widgets that come with the Barebones CMS. It is also the most flexible and powerful. If you need to write custom one-off HTML/PHP code (e.g. form + form handler) or do something specific that would be difficult to do with the other default widgets, then the Code widget can be the solution to the problem.
The Code widget is also the solution for those who want to hand code web pages while getting the benefits of the Barebones CMS (e.g. caching, the revision system, multilingual support, etc).
The Code widget offers a number of useful features to programmers:
The Code widget makes it easy to drop in PHP code anywhere on the page and feels like an included file thanks to some trickery involving global and reserved variables. All three sections (Head, Body, Action) are optional.
The Code widget is designed for one-off PHP scripts. Quick and dirty solutions to a problem without having to go create a whole new widget just for that one thing that will be used exactly one time. It offers three PHP code insertion points:
Those three aspects should cover 99.9% of all needs for one-off PHP code.
Since the Code widget also uses the Code Editor, it inherits all of the quirks and bugs of that reusable component. There are also a few other issues to take note of:
The Code widget is designed for PHP and HTML code that will be used exactly one time. It is annoying to clone PHP/HTML code stored within a Code widget.
If you need to reuse code, consider using either external include(s) and then using the include/require keyword inside a Code widget or simply create a new widget that does what you need. Creating a new widget is pretty easy to do. The Code widget exists for convenience to insert PHP/HTML code quickly.
If there is an error in the code, error messages will state something like "Error in eval()'ed on line...'. The Code widget uses the eval() language construct to execute code in the Head, Body, and Action sections.
Most variables that are global are accessible from within the Code widget thanks to some code that executes prior to calling eval().
Please keep in mind that all code is executed from within a function and all the limitations of PHP functions apply (e.g. have to use the 'global' keyword to have access to global variables by name). So there may be some global variables that are not accessible without using $GLOBALS or the 'global' keyword.