On Context

Data Forms

Data forms is a Wikidot feature which transforms pages in a particular category into structured data.

The primary intent of this feature is to normalize the look of all pages in a category — this makes sense in a wiki-focused setting, where page structure often consists of a number of headings followed by informative blurbs. Using data forms in this context is an easy and generally-reliable method of streamlining the user experience.

The most obvious change data forms makes is to the edit window. While editing a page in a data-formatized category, the edit window can look dramatically different, presenting buttons and checkboxes and select lists in addition to standard textareas for free editing. All edits and interactions with these features is stored in the page as data within separate fields, and the way this data is presented visibly is determined by the category's template.

Use on the SCP Wiki

Data forms has never been used on the SCP Wiki as intended.

The only use of data forms in the wiki's history has been in various collaborative logs, where the data-formatized category is treated as invisible, and the data from its pages is called via a ListPages module on a main hub page. This process creates an ever-expanding number of hard-to-access, nearly-contentless pages; this deficiency, combined with a lack of knowledge about data forms within staff, made them an irksome inclusion on the wiki. They were eventually removed and replaced with standard, static-data pages.

These collab pages had a number of signature features, including unique rating modules on every entry and streamlined page-creation.

Personal Use

Hi.

The author of this guide is Nagiros, a former SCP staffer noted for ver acquaintance with the data forms feature. I've used it in a number of projects, including:

• Tag Reports — A staff project to track tagging infractions, following the design of the old collab logs.
• Miller.aic Development Roadmap — A JIRA-esque list of issues and proposed changes to my Discord bot, likewise using the setup of calling data from a support category.
• Almeresh — A personal D&D 5e homebrew wiki which structures its categories via data forms. This is the way the feature was intended to be used.

Setting Up Data Forms

To data-formatize a page category, add the following basic syntax to the category template (i.e. /YOUR-CATEGORY:_template). Basic template looks like this; "FIELD" and "LABEL" can be anything you like; for example, if you have a section in the page for the history of a topic, "FIELD" might be something like "his" and LABEL might be "History".

[[form]]
fields:
  FIELD:
    label: LABEL
    type: TYPE
[[/form]]

The contents of the [[form]] determine what fields are extant in your database and how it's gonna look when you edit any of the pages in your category. Documentation is in the side bar here if you want to see what field types are available and all their properties. It's also probably good discipline to have consistent width values and defined height values.

There are a number of field types available, but the most common I've used have been text, wiki, and select.

One particularly interesting field type is pagepath. Pagepath allows you to select increasingly specific data from different parents, the flow and labels of which are mapped onto pages from another category. Parenting relationships between pages determines nesting level, and page titles equate to the label name. Pagepath outputs a link to the selected page, meaning it is likely intended to guide readers to related content.

The basic template, within the form on the _template page, looks like this:

  FIELD:
    label: LABEL
    type: pagepath
    category: PAGEPATH-CATEGORY

Although new options in the pagepath field can be created by adding new pages to the category in the usual way, it's recommended you use pagepath's built-in page-creation feature. To do this, select "Create new" in the pagepath dropdown. It will prompt you to enter the name of the item, and upon pressing Enter, a new page in PAGEPATH-CATEGORY: will be automatically created and parented as appropriate.

Despite its intent as a navigation tool, I've found more use for pagepath as a source to draw on for select fields across multiple formatized categories. On Almeresh, both the "character:" and "deity:" categories call for Alignment and Gender. While it's feasible to make these individual select fields and edit both whenever needed, setting up two support categories called "align:" and "gender:" with support pages within them is more convenient. That way, both lists are automatically updated and pull from the same sources.

The links created by pagepath's output can be obfuscated by wrapping the output in a [[span class="pagepath-disable"]] and adding the following CSS:

.template-table .pagepath-disable a {
  pointer-events: none;
  color: DEFAULT TEXT COLOR;
}

Displaying Data Forms

The intended way to display formatized pages is to add the following to the category template page, above the [[form]]:

[content]

====

[content] can be replaced by how you want the pages to look. You're able to use ListPages variables without actually implementing a ListPages module, which is pretty neat. You can call four special variables to display form data, which are %%form_raw{FIELD}%%, %%form_data{FIELD}%%, %%form_label{FIELD}%%, and %%form_hint{FIELD}%%. Documentation is here.

How you want each page to look is up to you, but try to display every field and field value in your data forms somewhere, so there's no missing info.

There are also ways to implement rudimentary conditional logic while displaying each page's contents. This isn't mentioned anywhere in official Wikidot documentation, but data forms mesh pretty well with expression blocks (documentation here). The basic syntax is below:

[[#if %%form_raw{FIELD}%% | display if true | display if false]]

So, if data exists within the specified field, you can choose to output a specific statement. This works with normal ListPages variables as well.

There are a couple limitations here. Firstly, the block terminates at the first ]] after [[#if, so you can't cleanly output date blocks or anything else that includes ]]. Secondly, I don't know of a way to create an if statement that checks for specific content within a field; all it can do is check if content exists.

The SCP wiki has historically ignored the formatized category and set up a hub page in _default:, however, this can be accomplished via the following:

Add the below basic template to the page of your choice.

[[module ListPages categories="YOUR-CATEGORY"]]

[[/module]]

The important stuff's gonna be what you want to put in the module body itself. You can use the four data forms variables from before, implemented the exact same way as any other ListPages variable.

Note that if any of your field-types are "date", you're going to need to implement a [[date]] block to get it to display properly. This mucks things up pretty hard if you've got any advanced formatting going on but there's very few ways around it. Feel free to change the field-type to "text" or "wiki" if it's an issue and treat the date like a text string — the only advantage is a little calendar pop-up in the edit window.

Date block looks like this:

[[date %%form_data{FIELD}%% format="WHATEVER"]]

Documentation on date blocks is here.

For the sake of convenience, you should provide a way to easily make new pages which will display in your ListPages. Two methods here: Using a link and using the NewPage module. Use the former if you don't care about the slugs/URLs of the hidden pages, use the latter if you do.

For the link method, place the below somewhere on your main page.

[/YOUR-CATEGORY:new-page/title/New%20Page/#_editpage Add New Page]

To ensure that people aren't just editing the same page over and over, you'll need to get someone with admin privileges on your site to turn on auto-numbering for your category. This can be found in the side bar under Appearances and Behavior, then down at the bottom in Autonumbering of Pages.

For the NewPage method, use the below. Documentation on the NewPage module is here.

[[module NewPage category="YOUR-CATEGORY" button="Add New Page"]]

If you would like to sort your page's content, edit the ListPages module so it has this text in the module arguments section:

order="@URL|ORDER"

ORDER can be any valid input from the ListPages documentation. It'll be what your readers see when they initially load the page.

Somewhere on that main page put a link that looks like the below:

[/MAIN-PAGE-NAME/order/ORDER | link text]

When clicked, the page's contents will shuffle to adhere to whatever ListPages order attribute is in that link. You can have multiple links on the page, of course.

The advantage of data forms here is that you can shuffle according to the contents of the custom fields you've defined. Do this by swapping out ORDER for _FIELD-NAME.

To create unique rating modules, go to your category template and place the following at the top.

[[module CSS]]
#header {
  display: none;
}
.page-rate-widget-box {
  position: fixed;
  top: 0;
  right: 0;
}
[[/module]]

[[module Rate]]

This keeps the rating module in a reliable position on the page with nothing visibly behind it. Note that the modification to #header may not be sufficient , depending on how your site is set up — the intent is to make transparent or block the display of any element in the top right corner which would overlap with the rating module.

Then go to your main page and adjust the contents of the ListPages to include this above every entry.

[[div class="rating-block"]]
[[iframe %%link%% class="frame-block" scrolling="no" frameborder="0"]]
[[/div]]

This uses an iframe to grab the rating module and then presents it on the main page. Note that the width and height values are specific to the Sigma-9 rating module and may need to be adjusted for personal use.

Additionally, add this CSS to the main page to bring the module parallel to the top of each ListPages entry, and correctly style the iframe.

.rating-block {
  float: right;
}
.rating-block > p {
  margin: 0;
}
.frame-block {
  width: 200px;
  height: 26px;
  overflow: hidden;
}

A notable deficiency with this feature is that, if you attempt to reverse your vote (e.g. changing a +1 to a -1 directly), the owindow which informs you that you've already rated will totally obscure the module, requiring you to refresh the page to remove it. As such, it is necessary to void your vote before reversing it.

Example Practice

The best way to get comfortable with data forms is via experimentation.

To practice, find a site you have moderator or admin privileges on and create a category template. Add the following to the page.

%%form_data{hello}%%

====

[[form]]
fields:
  hello:
    type: text
    label: Text
[[/form]]

Save the category template and create a new page in that category. You should be greeted by a single text input area, instead of the usual large edit window — type "Hello world!" into the field and save the page. The text you entered should now appear on the page before you.

Play around with this for a little bit, adding new text areas and adjusting the category template to display them. Then, you can start adding new field types to see how those operate — refer to the Wikidot documentation to see what types are available, and what their properties are.

After a while, it'll start to make sense.