http://www.perlmonks.org?node_id=587754

Editing DocLists

Background

DocList is a node type whose purpose is to contain a list of other nodes and some associated information. Technically, a doclist is a composition of:

  1. a list of node IDs (via the nodegroup db table) constituting the list itself;
  2. a text blob (via the document db table) associated with the list;
  3. a set of settings, aka "vars" (via the setting db table) for configuring the list's behavior/appearance.
In this FAQlet, the doclist being viewed is called the "parent", and the nodes contained in its list are called "children".

The DocList node type has associated code which allows a doclist instance to be represented in a variety of ways, so doclist editors have some flexibility in making each doclist most usable.

There are two subclasses of doclist: faqlist and tutlist. Only these subclasses are ever instantiated, not doclist. (You can think of doclist as an abstract base class, although technically nothing prevents it from being instantiated.) The subclasses (faqlist and tutlist) are nearly identical in all respects; the main difference have to do with permissions: SiteDocClan have authority to edit faqlists, and Pedagogues have authority to edit tutlists.

How to Edit

The doclist edit page has three parts, contained in two HTML forms. Be careful not to try to make changes in both forms at once, or you will be unhappy when you lose changes you thought you made.

  • The upper form contains the text blob editor, with "preview" and "update" buttons below it. How to use this editor should be pretty obvious.
  • The lower form contains the doc list editor and the settings editor, with "submit" buttons both above and below.
  • Making changes to the doc list:

    For info on making changes to the settings, see the next section.

    When done with your edits to the doc list and/or settings, click either the "Submit below" button above the doc list or the "Submit" button below the Settings.

    Settings

    When editing a doclist, you'll see at the bottom a place to enter arbitrary Settings (name/value pairs). This is presented in a table with a header row like:

    RemoveSettingValue

    Currently, all settings are boolean: you should set them either to 0 or to 1. Note that the default behavior for each setting (i.e. when not explicitly set) varies, and in some cases is context dependent.

    Note that a doclist's settings have no effect except when viewing the doclist directly. Any children which are doclists are shown using the parent doclist's settings. That is: if A and B are both doclists with their own settings, and B is a child of A, then B will be rendered with B's settings when viewing B directly, but will be rendered, like A, with A's settings, when viewing A. (I think we need to re-verify this. It doesn't quite sound right.)

    Currently available settings with behavior defined:

    What about this Show Auto checkbox?

    If turned on, an additional column is shown in the Settings table: Auto Set Value. It has something to do with nodeballs and other setting-related features. It is very rarely used, and in the context of doclists it is utterly superfluous and should be ignored. But if you're a curious devil, start with editvars.

    About DocStrings (tutstrings, faqstrings)

    A docstring has two parts: a title and a text.

    The title should not contain links/shortcuts, as it will be used as link text. It is really is the string node's title: monks can link to the string node by title using this value. Example: [SOPW]

    The text is free-form, and can contain links/shortcuts and other markup, as well as plain text.

    When editing a docstring, you can edit the title and the text.

    When viewing a docstring,

    When viewing a doclist which contains a docstring,

    When editing a doclist which contains a docstring,

    Bottom line: In the context of a doclist, ordinary users will only ever see the docstring's text.
    Even the authorized doclist editors will never see the child docstring's title, except when viewing the doclist in Edit mode.

    When linked as a node in normal situations (i.e. in the Chatterbox or in a post, rather than in a doclist), docstrings are not treated differently from other nodes. The link text is the docstring's title, and the link links to the docstring node itself. No automatic redirection or anything like that occurs, and the docstring's text is never used in the rendering of the link.