docs/package/pip/box.md

   1 # Box Package Installation Plugin
   2
   3 Deploy and manage boxes that can be placed anywhere on the site, they come in two flavors: system and content-based.
   4
   5 ## Components
   6
   7 Each item is described as a `<box>` element with the mandatory attribute `name` that should follow the naming pattern `<packageIdentifier>.<BoxName>`, e.g. `com.woltlab.wcf.RecentActivity`.
   8
   9 ### `<name>`
  10
  11 !!! info "The `language` attribute is required and should specify the [ISO-639-1](https://en.wikipedia.org/wiki/ISO_639-1) language code."
  12
  13 The internal name displayed in the admin panel only, can be fully customized by the administrator and is immutable. Only one value is accepted and will be picked based on the site's default language, but you can provide localized values by including multiple `<name>` elements.
  14
  15 ### `<boxType>`
  16
  17 #### `system`
  18
  19 The special `system` type is reserved for boxes that pull their properties and content from a registered PHP class. Requires the `<objectType>` element.
  20
  21 #### `html`, `text` or `tpl`
  22
  23 Provide arbitrary content, requires the `<content>` element.
  24
  25 ### `<objectType>`
  26
  27 Required for boxes with `boxType = system`, must be registered through [the objectType PIP](object-type.md) for the definition `com.woltlab.wcf.boxController`.
  28
  29 ### `<position>`
  30
  31 The default display position of this box, can be any of the following:
  32
  33 * bottom
  34 * contentBottom
  35 * contentTop
  36 * footer
  37 * footerBoxes
  38 * headerBoxes
  39 * hero
  40 * sidebarLeft
  41 * sidebarRight
  42 * top
  43
  44 #### Placeholder Positions
  45
  46 ![Visual illustration of placeholder positions](../../assets/boxPlaceholders.png)
  47
  48 ### `<showHeader>`
  49
  50 Setting this to `0` will suppress display of the box title, useful for boxes containing advertisements or similar. Defaults to `1`.
  51
  52 ### `<visibleEverywhere>`
  53
  54 Controls the display on all pages (`1`) or none (`0`), can be used in conjunction with `<visibilityExceptions>`.
  55
  56 ### `<visibilityExceptions>`
  57
  58 Inverts the `<visibleEverywhere>` setting for the listed pages only.
  59
  60 ### `<cssClassName>`
  61
  62 Provide a custom CSS class name that is added to the menu container, allowing further customization of the menu's appearance.
  63
  64 ### `<content>`
  65
  66 !!! info "The `language` attribute is required and should specify the [ISO-639-1](https://en.wikipedia.org/wiki/ISO_639-1) language code."
  67
  68 #### `<title>`
  69
  70 The title element is required and controls the box title shown to the end users.
  71
  72 #### `<content>`
  73
  74 The content that should be used to populate the box, only used and required if the `boxType` equals `text`, `html` and `tpl`.
  75
  76 ## Example
  77
  78 {jinja{ codebox(
  79     "xml",
  80     "package/pip/box.xml",
  81     "box.xml"
  82 ) }}