Download | Documentation | Forums

Global and Reserved Variables

While creating a website with Barebones CMS, it may become inevitable to integrate new functionality. As Barebones CMS grows in popularity, there will be a lot of developers mixing code together. This documentation covers standard interface development of predefined global variables and how to not conflict with other components. This is critical for a smooth Barebones CMS user experience.

All Barebones CMS globals start with the prefix '$bb_'. This prefix is reserved exclusively for the main Barebones CMS product. If you introduce new variables with the '$bb_' prefix, you will be beaten severely by community members.

You should consider most variables to be read-only as they are generally internal use only. If a function exists to manipulate the variable, use that function. If a function doesn't exist to manipulate some variable but you think it should, ask for it to be added to the main code.

Barebones CMS Core Globals

Core globals are global variables that are always available from widgets, shortcodes, and plugins within both the Barebones CMS frontend and editor.

$bb_dir

Type: String

Example: "."

The relative path from ROOT_PATH (config) to the current directory. This is used by various functions (e.g. BB_SaveLangPage()) to know where the page is located.

$bb_file

Type: String

Example: "index"

The base filename of the current file being executed. Typically 'index' but can be different. Used to build up filename strings like "index_en_us.php" for saving page changes.

$bb_relroot

Type: String

Example: ".."

The relative path to the ROOT_PATH (config) directory from the current directory. Files do not know where the configuration is until the directory is changed (using chdir()) and 'main.php' is loaded.

$bb_page

Type: Array

Example:

array(11) {
  ["ver"]=>
  float(1)
  ["redirect"]=>
  string(0) ""
  ["cachetime"]=>
  int(5)
  ["easyedit"]=>
  bool(true)
  ["sitemap"]=>
  bool(false)
  ["sitemappriority"]=>
  string(6) "normal"
  ["doctype"]=>
  string(22) "XHTML 1.0 Transitional"
  ["metarobots"]=>
  string(0) ""
  ["perms"]=>
  array(1) {
    ["_p"]=>
    array(0) {
    }
  }
  ["langs"]=>
  array(2) {
    ["en_us"]=>
    array(0) {
    }
    ["en"]=>
    string(5) "en_us"
  }
  ["defaultlang"]=>
  string(5) "en_us"
}

Contains language-neutral information about the current page. This content is stored as PHP serialized and base64 encoded or var_export() data along with other bootstrap information in '$bb_dir . "/" . $bb_file . ".php"'. The options are configured using the 'Edit Properties' and 'View Translations' page options.

$bb_profiles

Type: Array

Example:

array(2) {
  [""]=>
  string(7) "Default"
  ["mobi"]=>
  string(6) "Mobile"
}

Contains key-value pairs that map a cache profile to a human-readable string. See the Creating Cache Profiles documentation for more information.

$bb_profile

Type: String

Example: ""

Contains the current cache profile. Used for sending different content to the browser based on which cache profile is active. See the Creating Cache Profiles documentation for more information.

$bb_pref_lang

Type: String

Example: "en_us"

This is the language/translation that gets chosen by Barebones CMS based either on the 'lang' option in the query string or whatever the browser sends as its preferred language. It is used to locate the language-specific file to load (see $bb_langpage below).

$bb_langpage

Type: Array

Example:

array(4) {
  ["title"]=>
  string(0) ""
  ["metadesc"]=>
  string(0) ""
  ["widgets"]=>
  array(1) {
    ["root"]=>
    array(5) {
      ["_f"]=>
      string(9) "Root/Page"
      ["_m"]=>
      bool(true)
      ["_a"]=>
      string(4) "root"
      ["_id"]=>
      string(4) "root"
      ["_ids"]=>
      array(0) {
      }
    }
  }
  ["pagerand"]=> string(40) "bfd6e2f16062cfe3dba532c4b76383e17fafcc47"
}

Contains language-specific content about the current page. This content is stored as PHP serialized and base64 encoded or var_export() data in '$bb_dir . "/" . $bb_file . "_" . $bb_pref_lang . ".php"'. Pretty much everything about the current page is stored in this variable (e.g. widgets). The file that defines this variable is loaded only if Barebones CMS determines that the cached file is not supposed to be used.

$bb_lastwidgetupdate

Type: Integer

Contains the last global cache update timestamp and is therefore immune to file system idiosyncrasies. Updated when a file is saved through the editor or Flush Cache is used. The caching system uses this to determine if cached pages are out of date. Some widgets use this to determine if internally cached content needs to be refreshed (e.g. the Layout widget).

$bb_doctypes

Type: Array

Keys (Strings):

Contains page initialization/declaration of the DOCTYPE and opening 'html' tag. The key is stored in $bb_page["doctype"].

$bb_widget_id

Type: String

Example: "bb_code_code"

This is the unique identifier for the currently active widget in $bb_widget. Treat as a read-only variable. This is set using $bb_widget->SetID().

$bb_widget

Type: Object

Functions: SetID(), Save()

A reference object wrapper for the currently active widget. Stores the configuration for the widget. Do not call the SetID() or Save() member functions.

The Creating Widgets documentation has in-depth descriptions and examples on $bb_widget.

$bb_widget_instances

Type: Array

Maps a widget ID to an object instance of the particular widget class. You should never need to touch this.

$bb_filetosname

Type: Array

Maps a specific file name to static names that defines the class name and other critical information of the widget. This array is necessary during the widget loading and initializing phase because files in which widgets are declared are only included one time and there could be multiple instances of the same widget on the page. You should never need to touch this.

Barebones CMS Processing Globals

The processing globals are created and used while processing the widgets to generate a complete page. Except for $bb_mode, these variables are intended to be modified.

$bb_mode

Type: String

Valid values: "prehtml", "head", "body", "foot"

Defines the current mode/state of the BB_ProcessPage() function. Widgets have an opportunity in each state to perform relevant actions within their Process() function. The most common values of $bb_mode to perform actions with are "head" (inside the 'head' tags) and "body" (inside the 'body' tags).

Do not modify this variable. Doing so will wreak havoc.

$bb_css

Type: Array

An array that defines all the external CSS files to place on the page and, optionally, what media type those CSS files map to. Each key is a URL to the CSS file (usually an absolute path from the web root). Each value can be a string or an array. If it is a string, it should be an absolute path to the CSS file on the system. If it is an array, the first element should be an absolute path to the CSS file on the system and the second element should be the CSS media type (defaults to "all").

This approach minimizes the possibility of duplication by only writing out one reference per CSS file.

Only relevant when $bb_mode is "head".

$bb_usepremainjs

Type: Boolean

Default: false

This variable should only be set to true if BB_PreMainJS() is supposed to be called before including the Javascript files referenced by $bb_js. This will inject a number of Javascript variables that are found within the Barebones CMS editor and reusable components. This variable is typically set to true by more advanced widgets and shortcodes.

Only relevant when $bb_mode is "head".

$bb_js

Type: Array

An array that defines all the external Javascript (JS) files to place on the page. Each key is a URL to the JS file (usually an absolute path from the web root). Each value is a string that should be an absolute path to the JS file on the system.

Only relevant when $bb_mode is "head".

Barebones CMS Editor Globals

These variables are defined when inside the editor. Widgets and shortcodes always have access to the full set listed here (in the editor) but plugins may not depending on what hooks are involved.

$bb_plugin_actions

Type: Array

Tracks actions, callbacks, and priority/order of the callbacks for BB_RunPluginAction(), and BB_RunPluginActionInfo(). Adding elements is done via BB_AddPluginAction(). You should never need to touch this.

$bb_accounts

Type: Array

Example:

array(2) {
  ["users"]=>
  array(1) {
    ["test"]=>
    array(5) {
      ["type"]=>
      string(3) "dev"
      ["user"]=>
      string(4) "test"
      ["pass"]=>
      string(40) "a865db068fd75a53c8e6696bd8fb690a510f50ba"
      ["group"]=>
      string(0) ""
      ["session"]=>
      string(40) "bad685715297edf7b03ee792a5f0faf55726e059"
    }
  }
  ["sessions"]=>
  array(1) {
    ["c656bdf96e94059ee68fbddb73b26477f3b5f251"]=>
    array(3) {
      ["username"]=>
      string(4) "test"
      ["session2"]=>
      string(40) "e54c1601e56a608e76b2025b71aa29db485fe32f"
      ["expire"]=>
      int(1272892608)
    }
  }
}

A complete list of accounts and active sessions. This array is stored as PHP serialized and base64 encoded or var_export() data (accounts.php). There are quite a few functions to manipulate this array inside of functions.php.

$bb_account

Type: Array

Example:

array(5) {
  ["type"]=>
  string(3) "dev"
  ["user"]=>
  string(4) "test"
  ["pass"]=>
  string(40) "a865db068fd75a53c8e6696bd8fb690a510f50ba"
  ["group"]=>
  string(0) ""
  ["session"]=>
  string(40) "bad685715297edf7b03ee792a5f0faf55726e059"
}

The currently logged in account. This variable (e.g. $bb_account["type"]) and/or the function BB_IsMemberOfPageGroup() are typically used to determine if the user has permission to perform some action.

$bb_session

Type: Array

Example:

array(3) {
  ["username"]=>
  string(4) "test"
  ["session2"]=>
  string(40) "e54c1601e56a608e76b2025b71aa29db485fe32f"
  ["expire"]=>
  int(1272892608)
}

The current session of the currently logged in account. Generally only useful in the editor when logging out and changing the password.

$bb_langpagerevisions

Type: Array

Example:

array(3) {
  ["rootrev"]=>
  int(0)
  ["branches"]=>
  array(0) {
  }
  ["revisions"]=>
  array(1) {
    [0]=>
    array(5) {
      [0]=>
      string(0) ""
      [1]=>
      string(243) "[...PHP serialized $bb_langpage...]"
      [2]=>
      int(1270046720)
      [3]=>
      int(1270046720)
      [4]=>
      string(12) "Initial Page"
    }
  }
}

Contains every revision and branch of the current language-specific page ($bb_langpage). Only loaded when $bb_revision_num is greater than -1.

Each entry stores the branch name (empty string is "[Root]"), PHP serialized $bb_langpage, creation timestamp, last modified timestamp, and the reason for the revision. You should never need to touch this.

$bb_revision_num

Type: Integer

Example: -1

Tracks the current revision number of the language-specific content. Can be controlled via the URL option of 'bb_revnum'. -1 is the default value, which uses live language-specific content (the content users can see).

$bb_revision

Type: Array

Example:

array(5) {
  [0]=>
  string(0) ""
  [1]=>
  string(580) "[...PHP serialized $bb_langpage...]"
  [2]=>
  int(1272027863)
  [3]=>
  int(1272028930)
  [4]=>
  string(4) ""
}

The current revision (a copy) from $bb_langpagerevisions as specified by $bb_revision_num.

$bb_revision_writeable

Type: Boolean

Example: true

Declares whether or not the current revision is writeable. A revision is writeable if the revision is the latest version of any branch. You should never need to touch this.

$bb_def_extmap

Type: Array

An oddball variable for some oddball functionality. This is used primarily by the 'File Explorer' site option for mapping what happens when "Edit" is clicked based on the file extension. It was moved globally to better accommodate extra functionality such as the Syntax Highlighter shortcode. Very useful to add additional "Edit" handlers to 'File Explorer'.

Reserved Global Variable Prefix

Barebones CMS reserves the '$bb_' prefix for its own use. Variables with the '$bb_' prefix are also somewhat intended to be used by your widgets and plugins but usually through indirect means (i.e. a function call). One problem still remains: How to name global variables for widgets and plugins to avoid conflicts? One other prefix has been reserved for this purpose: '$g_'. The Barebones CMS core will never use the '$g_' prefix.

Important note: While '$bb_' is reserved, Barebones CMS utilizes regular variable names (no specialized prefix). If you use regular variable names, you may end up interfering with the proper operation of Barebones CMS. Even if there is no conflict right now, there might be a conflict in the future. Widgets and plugins need to be written such that they don't conflict with the main product nor conflict with each other. The '$g_' prefix is designed to eliminate such conflicts.

In general, you should avoid using global variables and use local class variables wherever possible. However, in some cases, global variables can be very convenient.

For global variables that you want to guarantee to be conflict free, you should use '$g_' with your class name. A basic example of this is the '$g_bb_content_' prefix used by the Content widget (internally known as 'bb_content').

For global variables that you don't care about getting overwritten by some other widget, use '$g_' without your class name. A basic example of this is the '$g_path' variable in the Content widget that is used to figure out where the shortcodes are located to load them into memory. It doesn't matter what happens to $g_path after the shortcodes are loaded.

© CubicleSoft