Help:Class

From Saintapedia
(Redirected from Start datetime)
Jump to navigation Jump to search

In Cargo, the first step in storing data in a structured way is creating a class.

Creating a class

Special:CreateClass

A template that stores data in a table needs to also either declare that table, or "attach" itself to a table that is declared elsewhere. Since there is usually one table per template and vice versa, most templates that make use of Cargo will declare their own table.

Enter all the data here to create the properties, template, form and category for a single class. For more options, use the pages Create a template, Create a form and Create a category instead.

Data types

Cargo supports various data types including simple types like strings, dates, and numbers, to more complex ones like hierarchies, coordinates, and wikitext.

Page

  • Holds the name of a page in the wiki
  • Default max size: 300 characters

String

  • Holds standard, non-wikitext text
  • Default max size: 300 characters

Text

  • Holds standard, non-wikitext text
  • Intended for longer values
  • Unindexed

Integer

Float

  • Holds a real, i.e., non-integer, number

Date

  • Holds a date without time

Start date,End date

  • Similar to Date, but are meant to hold the beginning and end of some duration. A table can hold either no Start date and no End date field, or exactly one of both.
  • Limitations - You could get an error:
    • There can be only one field of type Start date or Start datetime.
    • Error: There can be only one field of type End date or End datetime.

Datetime

  • Holds a date and time

Start datetime,End datetime

  • Work like Start date or End date, but include a time.
  • Limitations - You could get an error:
    • There can be only one field of type Start date or Start datetime.
    • There can be only one field of type End date or End datetime.

Boolean

Coordinates

  • Holds geographical coordinates

Wikitext string

  • Holds a short text that is meant to be parsed by the MediaWiki parser
  • Default max size: 300 characters
  • Purpose
    • This data type is for storing strings that might contain wiki markup, but they are treated primarily as text strings rather than parsed wikitext when displayed.
  • Use Case
    • Use this when you want to store text that might include wiki syntax, but you don't need this text to be rendered as wiki content every time it's displayed.
    • It's useful for storing content where the wikitext might be relevant only in certain contexts or for archival purposes where the raw text with markup is preserved but not necessarily executed.

Wikitext

  • Holds longer text that is meant to be parsed by the MediaWiki parser
  • Unindexed
    • Purpose
      • Designed to store content that includes MediaWiki markup, which should be parsed and rendered as wikitext when displayed. This means when you query this field in Cargo, the result will be formatted according to MediaWiki's parsing rules, turning wiki syntax into HTML.
    • Use Case
      • Ideal for fields where the content is meant to be dynamic or formatted, like descriptions, bios, or any content that should appear with links, bold, italics, lists, etc., as intended by the wiki markup.

Searchtext

  • Holds text that can be searched on, using the Special:MyLanguage/Extension:Cargo/Querying data#The "MATCHES" commandMATCHES command (requires MySQL 5.6+ or MariaDB 5.6+)
  • Purpose
    • If there's a need to differentiate content for searching purposes, one might treat certain text fields as plain text for indexing, but this isn't a native Cargo data type; instead, it's more about how data might be processed or indexed for search functionality.
  • Use Case
    • You might design your database to store content in one form (like Wikitext) but ensure that for searching purposes, a plain text version (Wikitext string could serve this purpose if not intended for rendering) is used to improve search accuracy and performance by avoiding the complexities of wiki markup.

File

  • Holds the name of an uploaded file or image in the wiki (similar to Page, but does not require specifying the "File:" namespace) (default max size: 300 characters)

URL

  • Holds a URL
  • Default max size: 300 characters

Email

  • Holds an email address
  • Default max size: 300 characters

Rating

  • Holds a "rating" value, i.e., usually an integer from 1 to 5

Special page

Cargo includes special pages like Special:CargoQuery for direct querying and Special:Drilldown for interactive data exploration.

On Special:CreateClass the options are:

Template name

The Template name....

Where to store the data

"Use the Cargo extension to store this template's data" can be toggled on or off.

If on, you must specify the "Name of Cargo table defined by template"

Output format

The options are:

Each of these formats can be customized further by using parameters like template, named args, or separator to control how data is displayed or separated within the result. Remember that the exact syntax and capabilities might depend on the version of Cargo you are using, so always check the latest documentation for the most current options and features.

Table

  • The table is the default output format for Cargo queries.
  • Results are displayed in a tabular format with each row representing a record and columns for each field of the record.

Example: 

{{#cargo_query:
|tables=ExampleTable
|fields=Field1, Field2
}}

Side Infobox

  • Side infobox is designed for displaying information in a box typically positioned to the side of an article.
  • This format creates a box that can be floated to the right or left of content, useful for displaying metadata or summary information about a subject.

Example: 

{{#cargo_query:
|tables=ExampleTable
|fields=Field1, Field2
|format=infobox
}}

Plain Text

  • Use this when you need the output in plain text, without any HTML formatting.
  • This format removes all HTML tags and presents data in a straightforward text manner, which can be useful for embedding data in text or for custom formatting.

Sections

  • Sections are useful when you want to organize information into sections within a page.
  • Each record is displayed as a section, often with a header. This format is handy for creating detailed pages where each section represents different aspects or entries of a subject.

Example: 

{{#cargo_query:
|tables=ExampleTable
|fields=Field1, Field2
|format=sections
}}

Options

This template can be included multiple times on the page

The template will be able to store multiple sets of data for different instances of itself on the same page. This feature leverages MediaWiki's templating system to iteratively display data stored via Cargo, enhancing the dynamic and flexible presentation of information stored in a structured manner within the wiki.

In practice, this capability allows wiki editors to:

  • Create lists or galleries where each item follows the same format but displays different data (e.g., a list of events, publications, personnel bios, etc.).
  • Implement dynamic content sections where each section might focus on different aspects of similar data, like different product features or specifications, all on the same wiki page
Data repetition

Cargo allows for storing structured data in MediaWiki pages. When you create templates to display this data, you might want to use the same template structure to show different sets of data. For example, if you have a template for displaying book information, you might want to use that template multiple times on one page to list several books.

No conflict in data display

Each instance of the template should be able to pull and display different data sets without the instances interfering with each other. This means:

  • Unique Identifiers: If the template generates or uses any HTML IDs or JavaScript variables, they need to be unique for each instance to avoid conflicts in the DOM or in scripts.
  • Data Parameters: The template should be designed to accept parameters or use Cargo queries that can specify which piece of data (or which set of data) it should display each time it's called.
Dynamic content handling

Since Cargo often involves querying data from wiki pages or databases:

  • Each template call might query different data. If the template uses #cargo_query, each instance can define different parameters for what data to fetch, allowing for different content in each template instance.
  • Scope of Variables: Variables used within the template for storing or manipulating data should not leak or overwrite each other between different template instances.
Efficiency

Even though templates can be included multiple times, there should be considerations for:

  • Page Load Time: Multiple queries or complex template processing might slow down page loading if not optimized.
  • Cargo Query Optimization: Efficient use of Cargo's ability to limit, join, or filter data to reduce unnecessary database hits or compute overhead with each inclusion.
Modular design

Such templates are usually designed to be modular and reusable, meaning they:

  • Are built with the idea that their content will change with each use, based on the parameters passed or the data queried.
  • Maintain Consistency: While they can show different data, the format and style remain consistent, which is useful for maintaining a uniform look across different content on the same page..

Use full wikitext instead of #template_display

You need to manually write out how you want template data to appear using MediaWiki's language, rather than relying on the automated or semi-automated display mechanisms provided by extensions like Cargo. This approach is chosen for greater control, customization, or when the display logic provided by extensions does not meet the specific needs or design requirements of the page.

Example Setup: Create a Template: Let's say you have a template named ExampleTemplate that you want to use for displaying data from a Cargo table called ExampleTable. Template Code (Template:ExampleTemplate): mediawiki 

<div class="example-box">
<h2>{{{name|}}}</h2>
<p><strong>Description:</strong> {{{description|No description provided}}}</p>
<p><strong>Year:</strong> {{{year|Unknown}}}</p>
</div>

Cargo Query with Full Wikitext: Wiki Code: sql 

{{#cargo_query:
|tables=ExampleTable
|fields=name, description, year
|format=template
|template=ExampleTemplate
|use full wikitext=true
}}

By setting use full wikitext=true, the template parser will interpret all wikitext within the template, allowing for more complex layouts, headings, classes, etc., as defined in your template.

Explanation:

  • ExampleTable: This is your Cargo table containing fields like name, description, and year.
  • ExampleTemplate: This template formats how each row from ExampleTable will be displayed.
  • {{{name|}}} means it will display the name field, with an empty string if name is not provided.
  • {{{description|No description provided}}} shows the description or a default message if none exists.
  • {{{year|Unknown}}} similarly handles the year.

Query Parameters:

  • format=template specifies that we're using a template for output.
  • template=ExampleTemplate tells Cargo which template to use.
  • use full wikitext=true enables the full wikitext interpretation within the template.

This method allows for richer, more customized display options directly from your Cargo query results, integrating seamlessly with MediaWiki's text processing capabilities.

The options are:

#template_display

This would be a parser function or a similar mechanism provided by extensions like Cargo or Semantic MediaWiki to display template data in a more formatted or structured way. When you use something like #template_display, it implies you're leveraging the extension's capabilities to handle how the template's content is shown, potentially simplifying the wikitext and making use of predefined display formats like infoboxes, tables, etc.

Full Wikitext

This means instead of relying on an extension's shorthand or parser functions to display data, you would write out the full wikitext yourself. This approach gives you complete control over how the information from templates is displayed. You're not using a pre-formatted display function provided by Cargo or another extension; instead, you're crafting how each piece of data from the template looks using standard MediaWiki markup. This could involve manually creating tables, divs, spans, and using inline styling or classes for layout and design.

  • Customization: You have the freedom to customize every aspect of how the data is presented. If you want a specific layout that's not easily achievable with the default settings of #template_display, you'd opt for full wikitext.
  • Complexity: It can be more complex and verbose because you're writing out all the formatting code instead of letting an extension handle it with simpler syntax.
  • Learning Curve and Maintenance: It might require a better understanding of MediaWiki syntax and potentially could be harder to maintain if the structure of your data or the desired display format changes frequently.
  • Performance: On some wikis, avoiding complex parser functions for every template might lead to slightly better performance in terms of page rendering time, especially if the wiki has many such templates, since parser functions can sometimes be computationally heavier than straightforward wikitext.
  • Compatibility: If there's a concern about compatibility with different extensions or future changes in how extensions handle template display, using full wikitext might ensure your pages look consistent regardless of changes in the extensions.

Form name

The "Form name" is used...

Category name

The "Category name" is used...

Template fields

Customization

Through settings like $wgCargoDefaultStringBytes or $wgCargoMaxQueryLimit, administrators can control how Cargo behaves in terms of data storage limits or query performance.

Retrieved from ‘https://saintapedia.org/w/index.php?title=Help:Class&oldid=7211#Start_datetime,End_datetime’