User Tools

Site Tools


meta:template_dataentry_background

Dataentry template background

What is it?

The dataentry template contains the template for so called dataentry pages.
Dataentry pages contain the bare technical facts of routers (and other devices) related to OpenWrt, and are the datasource for the Table of hardware. When a dataentry page is either read or changed, the data contained in it is fed into a sqlite database.

To get the data out of this database, simply create datatables / datalists / tagclouds on a page.
For examples, see template_device, datalist-csv or Dataclouds.
For more information on how this works, see https://www.dokuwiki.org/plugin:data

When to use it?

Do create a new dataentry page IF

  • you have the information available that is required for a new dataentry
  • the device is not yet listed in the Table of Hardware
  • the device has versions with differing hardware, compared to an already existing device in the toh, e.g. v1 = 32MB RAM vs. v2 = 64MB RAM.

When not to use it?

Do not create a new dataentry page IF

  • the version number increased, but none of the hardware listed in the dataentry has changed

Usage

Creating new entries

Editing existing entries

On the dataentry pages, which you can find in the Table of Hardware, you can edit the values in two ways:

  1. Preferred: Special "edit" link below the left corner of the dataentry: You will see a form for easy editing the dataentry.
    The form avoids accidentially ruining the dataentry structure and also provides dropdowns for easy filling in some values.
  2. Deprecated: Standard dokuwiki "edit" link on the right or "Edit this page" on the top: You will see the dataentry in wiki language.
    You can accidentially ruin the dataentry structure.

See below for detailed description and allowed values of each field.

Example

====== Techdata: EXAMPLE DIR-509 v0.99 ======
~~HIDEPAGE~~

{{page>meta:infobox:dataentry_topnote&noheader&nofooter&noeditbtn&inline&indent&link}}


/*********************************************************
*                 >>>>>>>> ! <<<<<<<<
* -------- >>>>>>>>  W A R N I N G  <<<<<<<<--------
*                 >>>>>>>> ! <<<<<<<<
*
*   If you can read this, YOU ARE DOING IT WRONG.
*
*   To edit this page in the only right way, do this:
*   1) Click "Cancel", then
*   2) edit this page ONLY via the lower LEFT edit button.
*
*   In case you disobey to the above: You break it, you pay it.
*   Thank you for respecting the rules of this wiki.
*
*   --- Your wiki administration
*********************************************************/

===== Dataentry =====
---- dataentry techdata ----
Device Type_devicetype                : (Wifi router) # If 'other' -> request new devicetype @wiki admin
Brand                                 : (EXAMPLE) # ===>  Mandatory  <===
Model                                 : (DIR-509) # ===>  Mandatory  <===
Versions                              : (v0.99) # List versions comma separated: v1, v1.1, v1.5, v2, v2.5
Availability_availability             : (Available 2016) # 
Supported Since Rev_url               : (https://dev.openwrt.org/changeset/12345) # https://dev.openwrt.org/changeset/xxxxx
Supported Since Rel_releasesince      : (14.07) # First official release (i.e. not trunk)
Supported Current Rel_releasecurrent  : (15.05.1) # Current official release (i.e. not trunk)
Unsupported                           : (USB) # e.g. '5GHz wifi'; Describe what is not supported
Platform                              : (Atheros AR9133) # e.g. Atheros AR9331; Broadcom BCM6361
Target_target                         : (ar71xx) # https://dev.openwrt.org/wiki/platforms
Instruction Set_instructionset        : (MIPS32) # https://en.wikipedia.org/wiki/List_of_instruction_sets
Sub Instruction Set_subinstructionset : (MIPS32 42K/E series) # 
Bootloader_bootloader                 : (U-Boot) # http://wiki.openwrt.org/doc/techref/bootloader
CPU MHz                               : (2x 499) # pure number without 'MHz'; use 'x' to show multiple cores, e.g. 2x 400;
Flash MB_mbflashs                     : (46) # CTRL+click for multiselect
RAM MB_mbram                          : (218) # 
Ethernet 100M ports_numethport        : (-) # Number of 100Mbit ethernet ports
Ethernet GBit ports_numethport        : (7) # Number of Gbit ethernet ports
Switch                                : (Atheros AR8362) # e.g. Atheros AR8236
Modem_modem                           : (VDSL3-) # Select type of modem
Comments network ports_               :  # Comments on Ethernet, Fibre and Modem
VLAN_yesno                            : (No) # 
WLAN Hardwares                        : (Atheros AR9113, Atheros AR9224) # e.g. Atheros AR5416; separate multiple by comma; add '#x (mini-)PCI(e)' if necessary.
WLAN 2.4GHz_wlan24                    : (n) # 
WLAN 5.0GHz_wlan50                    : (ac) # 
WLAN Comments_                        :  # MIMO and other WIFI information
Detachable Antennas_numdetachantenna  : (12) # Number of detachable antennas
USB ports_usbmultiselects             : (3x 2.0, 2x 3.0) # Number of USB2.0 & 3.0 ports; CTRL+click for multiselect
SATA ports_numsataport                : (-) # Number of SATA or eSATA ports
Comments USB SATA ports_              :  # Comments on USB, SATA and eSATA ports
Serial_yesno                          : (Yes) # 
JTAG_yesno                            : (Yes) # 
LED count_numled                      : (8) # Number of (user configurable) LEDs
Button count_numbutton                : (3) # Number of (user configurable) buttons/switches (other than Power)
Power Supply                          : (12 VDC, 2.0 A) # Specifications of Power Supply (Volt, Amp) or Battery (Volt, mAh)
Device Page_page                      : (toh:d-link:dir-505) # toh/brand/brand_model_version
Device Techdata_hidden                : View/Edit data # ===> Mandatory, must be "View/Edit data" <===
Forum Topic URL_url                   : (http://¿) # forum.openwrt.org/viewtopic.php?id=xxxxx
WikiDevi URL_url                      : (http://¿) # wikidevi.com/wiki/yourdevice
OEM Device Homepage URL_url           : (http://¿) # yourbrand.com/yourdevice
Firmware OEM Stock URL_url            : (http://¿) # yourbrand.com/yourdevice/stockfirmware
Firmware OpenWrt Install URL_url      : (https://downloads.openwrt.org/chaos_calmer/15.05.1/ar71xx/generic/openwrt-15.05.1-ar71xx-generic-dir-505-a1-squashfs-factory.bin) # downloads.openwrt.org/latest/…factory.bin; If more than 1 file for install/upgrade -> link to download *folder* instead of image
Firmware OpenWrt Upgrade URL_url      : (https://downloads.openwrt.org/chaos_calmer/15.05.1/ar71xx/generic/openwrt-15.05.1-ar71xx-generic-dir-505-a1-squashfs-sysupgrade.bin) # downloads.openwrt.org/latest/…sysupgrade.bin; If more than 1 file for install/upgrade -> link to download *folder* instead of image
Picture_img100s                       : (media:example:dir-509_general_view.jpg) # media:brand:model_general_view.jpg; Single general picture to identify the device; detail pictures to be provided on device page. How to add images: http://wiki.openwrt.org/meta/adding_images_to_openwrt_wiki
Comments_                             :  # Anything that is worth mentioning
----

{{section>:meta:template_dataentry_background#conventions_for_dataentry_values&nofooter&noeditbtn}}

Conventions for dataentry values

General nomenclature

Details

Conventions per characteristic

Details

Technical background

  • Why this template?
    • Automated toh creation with comfortable filtering option through usage of Structured data plugin for Dokuwiki
  • Mode of operation (How does this work?)
    • required: Dokuwiki Structured data plugin
    • required: Dokuwiki sqlite plugin (for structured data plugin)
    • required: Dokuwiki Include plugin (for including permanote, see below)
    • required: Dokuwiki server: php5-sqlite
    • required: dataentry (see above) on device page or on separate technical data page
    • required: data pages with {{page>meta:infobox:dataentry_permanote&noheader&nofooter&noeditbtn}} (this will include an infobox regarding usage of the dataentry in each of the dataentry pages)
    • required: page/infobox dataentry_permanote, which contains the permanent usage notes to be included in the data page (see above)
    • required: wiki page containing a datatable section → see https://www.dokuwiki.org/plugin:data#data_table_output for details
  • Why the '_' at the end of 'Status_' and other characteristics ending in 's'?
    Why 'ss' where 's' would be the correct spelling?
  • Why separate technical data pages? Why not include the technical data in the device pages?
    • In general, dataentries can be placed either
      • on the device page: Anywhere, at the beginning, at the end, in the middle… it doesn't matter. OR
      • on separate dataentry page (one dataentry page per device / per device version)
    • For different versions of a device, different dataentry files must be created anyways (only one dataentry section per page allowed). This means:
      • Separate the technical data (dataentry) from the device page
      • Put dataentry pages in separate namespace techdata (one dataentry page per device / per differing device version)
    • Multiple dataentries on the same page are possible, but do not lead to the desired result, see footnote #1: https://www.dokuwiki.org/plugin:data#fn__1
      "any additional dataentry on the same page would overwrite any preceding dataentry on this page and so - while many dataentry blocks on one page may be displayed - only the values of the last one would be stored in the SQLite database and could be retrieved as an output by e.g. a datatable"
      → Any HW version with different technical data needs separate dataentry page, in order for the automatedly created toh to work correctly.
  • Why the Datatype aliases? What do these aliases do, how do they work?
    • By adding a datatype alias like _modem, _yesno, _brand, _target, etc., you can define valid values for the respective field, which finally leads to the dataentry editor displaying drop down fields instead of simple textboxes. → User can click and select instead of typing in the value → no different spelling, no need to enter ¿ manually ;-)
    • Aliases and the valid values are defined in admin / Data Plugin: Field aliases

Multiple ToHs

Since it is so easy to create a toh, it's no problem to create multiple tables with different content (columns).
The general OpenWRT user may only be interested in the columns as shown above, while other users may whish to have other columns (e.g. what flash chip / RAM chip is used). Whatever the user wants to see in this table: Take a subset of characteristics out of the template, put them in a new wiki page, and you're done. It can't be much easier, can it?

Permanent note

Users need to be kept from doing silly things, that could break the functionality of the data plugin. Therefore, a permanent note shall be included in every dataentry page. In order to define and later on edit the permanent note in only one place, we need an infobox:

Content of meta:infobox:dataentry_topnote

===== Usage =====
  * Edit the dataentry via the **LEFT** edit button below the box
  * For adding new dropdown values, contact the wiki admin.
  * For conventions / allowed values, see below
  * For general usage help, see [[:meta:template_dataentry_background|Dataentry template background]]

To include the infobox in the dataentry pages, simply add this: {{page>meta:infobox:dataentry_topnote&noheader&nofooter&noeditbtn}}

Remark: This Infobox can surely be styled like the other infoboxes already available here: http://wiki.openwrt.org/meta/infoboxes

Including help for column values into datapages

To include detailed help regarding allowed values and formatting etc. in the dataentry pages, simply add this below the dataentry: {{page>:meta:template_dataentry_background#conventions_for_dataentry_values&nofooter&noeditbtn}}

This is the same way as with including the permanent note above and has the advantage, that you can include this big section in each datapage by adding minimal code, and if something needs to be changed, you only need to change one page, which then is automatically included in all available device- and datapages.

meta/template_dataentry_background.txt · Last modified: 2017/02/11 17:05 by tmomas