PageBlocksEditor

Page Blocks

Overview

When the module export has the blocks field defined, the structures in that array will be used to output a web page. Each block can be a form, list, link, SWF object or function. It can also have raw HTML code around it if needed. The form and list can use SQL queries to get the fields from the database. This article describes the available page block functionality.

Note that you can add the blocks manually with specific ModuleManager method calls. They are described in the appropriate sections. Or you can use the ModuleManager.addBlock() instead.

Common fields

The _ExportBlock type holds the parameters for page blocks. This section describes the parameters common for all block types.

Field	Description
htmlPre	HTML code to output before the block.
htmlPost	HTML code to output after the block.
title	Page block title.
type	Page block type.

List

The BLOCK_LIST block type outputs a list in the form of a HTML table to the page. It allows outputting data from SELECT SQL query with last column containing the available actions for that row. The list can have page counters.

The list can be added to the webpage with ModuleManager.addList() call.

Field	Description
actionPre	List action prefix.
actions	List actions list.
actionPost	List action postfix.
fields	List columns.
fieldsExt	Extended list columns.
pageRows	Maximum rows count per page.
pageAction	Action for next list page link.
pageCount	List page count query.
query	List or form SQL query.
queryTrace	If enabled, displays query string before the list.

The extended list columns allows the possibility to do one of two things: output the "params" row field parameter or output the list field text with a given function.

Basic usage example:

{
  type: BLOCK_LIST,
  action: "core/quest.",
  actions: [ "edit" ],
  actionPost: "&chainid=[row.chainid]",
  query: "SELECT q.*, " +
    "FROM Quests AS q " +
    "ORDER BY q.Name, q.Note",
  fields: [ 'id', 'chain', 'name', 'note' ]
}]

This basic example will output the list of all quest chains. Each of the rows will have an edit action that will lead to something like this: http://your-editor.com/index.n?a=core/quest.edit&id=123&chainid=456. Note the [row.chainid]. This is an extension of string parsing for list block type. It allows using a database row field in a string.

Pages usage example:

{
  type: BLOCK_LIST,
  pageRows: 50,
  pageAction: "?a=core/user.search&name=[name]",
  pageCount: "SELECT count(*) AS cnt FROM Users " +
    "WHERE lower(Name) LIKE '%' || lower([name]) || '%'",
  action: "core/user.",
  actions: [ "edit", "del" ],
  query: "SELECT * FROM Users " +
    "WHERE lower(Name) LIKE '%' || lower([name]) || '%' OR " +
      "lower(NetworkID) LIKE '%' || lower([name]) || '%' " +
    "ORDER BY Name",
  fields: [ 'id', 'networkid', 'name', 'isbanned' ]
}]

This example is taken from core user module. It outputs a list of users that have a name containing a string given in "name" parameter. The list will be split into pages each containing 50 rows. There will be clickable page numbers above and below the list.

Extended fields usage example:

{
  type: BLOCK_LIST,
  action: "core/quest.",
  actionPost: "&chainid=[id]",
  actions: [ "edit", "del" ],
  query: "SELECT * FROM Quests " + 
    "WHERE ChainID = [id] ORDER BY ID",
  fields: [ "id", "name", "note", "author", "isdaily", "ischecked", "isvisible" ],
  fieldsExt: [
    { name: "isdaily", param: "isDaily" },
    { name: "ischecked", func: questListIsChecked } 
    ]
}

  function questListIsChecked(row: { ischecked: Bool, id: Int, chainid: Int },
      vars: Vars, perms: String)
    {
      if (manager.checkPermissions('core/questcheck.toggleChecked', perms))
        H.link({ 
          a: 'core/questcheck.toggleChecked&id=' + row.id + '&chainid=' + row.chainid, 
          text: '' + row.ischecked });
      else p(_('' + row.ischecked));
    }

This example is taken from core quest chains module. It outputs a list of quests in a chain with extended columns "isdaily" and "ischecked". The "isdaily" column will contain the value of "params.isDaily" field (for example, if "params" is {"isDaily":true}, then it holds true). The "ischecked" field contains a link to toggle checked status for a quest if the current editor user has permission for it. In the other case, only the value will be displayed.

Note that you also need have "isdaily" and "ischecked" strings in the "fields" array.

Form

The BLOCK_FORM block type outputs a form into the page. The form can contain a number of different inputs explained below. The input values can be taken from the results of SQL query.

The form can be added to the webpage with ModuleManager.addForm() call.

Field	Description
enctype	Form encoding.
inputs	Form inputs list.
query	Form SQL query.
queryTrace	If enabled, displays query string above the form.
width	Form width.

The sections for different input types will contain all of the examples.

Common input parameters

Field	Description
isParam	If enabled, will get form input value from JSON object string in params field of the form SQL query.
name	Form input name.
title	Form input title.
type	Form input type.
value	Form input value.

Text

The INPUT_TEXT input type is the default type. It outputs a titled text field into the webpage.

Usage:

{ title: "Name", name: "name" }

Password

The INPUT_PASSWORD input type outputs a password text field with symbols replaced with asterisks.

{ title: "Name", name: "name", type: INPUT_PASSWORD }

File

The INPUT_FILE input type is used to upload files to webserver.

Usage example (full block):

{
  type: BLOCK_FORM,
  title: "Upload (CSV)",
  action: "core/locale.upload",
  enctype: "multipart/form-data",
  inputs: [
    { title: "File", name: "file", type: INPUT_FILE }
  ]
}

This example displays a form with a file input field. The example handler for this form is in the "Uploading files" section of Modules article.

Value

The INPUT_VALUE input type shows the value it is given but does not allow editing it.

Usage example:

{ title: "Register Date", name: "regdate", type: INPUT_VALUE }

Text area

The INPUT_TEXTAREA input type will output editable text area.

Field	Description
cols	Text area columns.
rows	Text area rows.

Usage example:

{ title: "Note", name: "note", type: INPUT_TEXTAREA }

Checkbox

The INPUT_CHECKBOX input type will output a checkbox.

Usage example:

{ title: "Is Visible?", name: "isvisible", type: INPUT_CHECKBOX }

Select

The INPUT_SELECT input type will output a dropdown list. There are two ways to fill it with values. One is through the results of SQL query and the other is directly with an array of objects.

Field	Description
query	SQL query. Should return { name, value } pairs.
values	List of select values.

SQL query usage example:

{ title: "Attribute", name: "name", type: INPUT_SELECT,
  query: "SELECT Name, StringID AS Value " +
    "FROM UserAttributeTypes ORDER BY Name" }

Array of name-value pairs usage example:

{ title: "Operator", name: "operator", type: INPUT_SELECT, 
  values: [
    { name: "=", value: "=" },
    { name: ">=", value: ">=" },
    { name: "<=", value: "<=" }
  ]}

Header

The INPUT_HEADER input type outputs a centered header in the form that can be used for grouping values in large forms.

Usage example:

{ title: "Group title", type: INPUT_HEADER }

Date/Time

The INPUT_DATETIME input type outputs the date/time picker. The textfield for it looks like a normal textfield but clicking on it will show the calendar on top.

{ title: "Start date (DD.MM.YYYY HH:MM)", name: "datestart", type: INPUT_DATETIME }

JSON

The INPUT_JSON input type is specific to the case when the "isParam" flag is set. It will take the field from the parsed "params" object and string it back into JSON. This may be needed for quick access to some dynamic structure that you don't want to make a complicated editor for.

Usage example:

{ title: "Prize (JSON)", name: "prize", isParam: true, type: INPUT_JSON }

For example, if the "params" field is {"amount":100,"prize":{"id":10,"autoUse":true}}, then the form textfield will hold the {"id":10,"autoUse":true} string. You can use the following export handler to put it back into the "params" field:

{
  action: "prize.update",
  table: "Prizes",
  updateParams: [ 'json:prize' ]
}

Link

The BLOCK_LINK block type outputs a HTML link.

Field	Description
action	Link action.

Usage example:

{
  type: BLOCK_LINK,
  title: "Check for errors",
  action: "core/questcheck.check"
}

Function call

The BLOCK_FUNC block type calls a module method to output a page block.

Field	Description
func	Module method to call.

Usage example:

{
  type: BLOCK_FUNC,
  func: listInventory
}

  function listInventory(vars: Vars)
    {
      p('here goes the inventory list');
    }

SWF object

The BLOCK_SWF block type outputs an SWF object to the page.

Field	Description
file	Local file name.
height	SWF object height.
width	SWF object width.

Usage example:

{
  type: BLOCK_SWF,
  width: 200,
  height: 100,
  file: "client/items/[id].swf"
}

Hidden value

The INPUT_HIDDEN input type adds the value it is given into the HTML code but does not show it in the form.

Usage example:

{ name: "secretID", value: 20, type: INPUT_HIDDEN }