Hulp: TemplateData

Van Wikipedia, de gratis encyclopedie
Spring naar navigatie Spring naar zoeken

Dit element maakt het genereren van informatie mogelijk via sjablonen waarmee geldige integraties kunnen worden gecontroleerd en automatische documentatie en toepassingsnotities kunnen worden gemaakt.

reden

De als TemplateData overeengekomen informatie over het doel van de template en vooral de gedetailleerde beschrijving van de parameters hebben twee toepassingsgebieden:

  • Creëren van een gestandaardiseerde documentatiepagina of een substantieel deel ervan
  • Evaluatie en automatische generatie van invoerformulieren voor de parameters, evenals een geautomatiseerde geldigheidscontrole van de waarden zodra ze zijn ingevoerd. Hiervoor zijn momenteel twee toepassingen:
    1. VisualEditor - huidige gelegenheid voor de ontwikkeling.
    2. Template Master - eerdere benadering, via een XML- specificatie; met een invoerformulier om in de brontekst van de wikipagina in te voegen. Als er geen (meer gedetailleerde) XML-beschrijving beschikbaar is voor een specifiek sjabloon, wordt de TemplateData-structuur gebruikt als alternatief om een ​​invoerformulier te maken en de geldigheid van de invoergegevens te controleren.

Het basisprincipe is ontleend aan gangbare softwaredocumentatietools ; is gebaseerd op de informatie die met javadoc kan worden verkregen.

Technisch gezien is de TemplateData gecodeerd in een <templatedata>...</templatedata> element, dat wordt beschreven onder JSON . De software geeft de inhoud automatisch weer in de vorm van een tabel, die in principe kan worden gebruikt om de conventionele parameterdocumentatie te vervangen. Voorwaarde is syntactische en semantische correctheid.

Deze zijn gekoppeld aan de sjabloondefinitie. In de Duitstalige Wikipedia moet dit altijd op de documentatiepagina / docu gebeuren en niet direct in de broncode van de sjabloonprogrammering.

  • In de versiegeschiedenis van de eigenlijke programmering mogen alleen wijzigingen in de effectieve programmering voorkomen, maar ondergeschikte bewoordingen nooit ondergeschikt aan de documentatie; deze hoort dus thuis op de subpagina / documentatie.

Het element <templatedata>…</templatedata> altijd opgenomen in een {{ TemplateData }} , die een frame en een link naar deze <templatedata>…</templatedata> geeft.

De inhoud van TemplateData is bedoeld om eenvoudige en korte teksten aan te bieden in een universeel bruikbaar formaat; bijvoorbeeld in tooltips of geautomatiseerde documentatiesystemen onafhankelijk van het wiki-project. Uitgebreide en complexe representaties moeten nog worden voorbereid in een aparte wikitekst.

Op formulieren gebaseerde creatie en verwerking

Deze tool van MediaWiki kan alleen worden gebruikt wanneer voor de eerste keer een TemplateData-documentatie wordt gemaakt.

  • Het geeft er de voorkeur aan om op de programmeerpagina te schrijven.
  • In de Duitstalige Wikipedia wordt echter langere documentatie niet op de programmeerpagina geschreven, maar in een aparte subpagina /Doku , zodat wijzigingen aan de programmering die effectief zijn alleen in de versiegeschiedenis van de integrerende pagina's verschijnen, en niet elke correctie van fouten in de documentatie, het opnieuw opbouwen van mogelijk duizenden integrerende pagina's met zich meebrengt.
  • Verder worden een uitgebreide syntaxis en een sjabloonparameter gebruikt; daarom moeten er later wijzigingen worden aangebracht in JSON ; of er wordt een speciale sjabloonsyntaxis gebruikt: Sjabloon: TemplateData / JSON .

Stap 1: Roep de sjabloondocumentatie-editor op

Het TemplateData-element kan automatisch worden gegenereerd op de sjabloon- of hun documentatiepagina's door naar de bewerkingsmodus te gaan en op de knop Sjabloongegevens beheren bovenaan de pagina te klikken. Bestaande TemplateData-elementen kunnen vervolgens op dezelfde manier worden bewerkt.

Belangrijk: Als er een nieuw TemplateData-element moet worden gemaakt, moet altijd eerst de sjabloonpagina worden opgeroepen, omdat dit de enige manier is waarop de volgende editor automatisch alle parameters van de sjabloon kan vinden en importeren. Het templatedata element dat aan het einde is gemaakt, zoals hieronder beschreven, moet vervolgens worden gekopieerd naar de bijbehorende documentatiepagina en de wijzigingen aan de sjabloonpagina worden genegeerd.

Stap 2: Laat de parameters automatisch importeren of voeg ze handmatig toe

Afbreken
Editor voor sjabloondocumentatie
Gebruik maken van

taal
OOjs UI-pictogram expand.svg
Duitse
taal toevoegen
Sjabloonbeschrijving (de)
Korte beschrijving van de sjabloon

0
Voorgestelde opmaak van wikitekst
Niet gespecificeerd OOjs UI-pictogram inline.svg In lijn OOjs UI-pictogram block-ltr.svg blok OOjs UI-pictogram advanced.svg Aangepast
Aangepast formaat tekenreeks
Tekenreeks voor sjabloonparameterindeling
Sjabloonparameters
VisualEditor-pictogram parameter-set-ltr.svg Voeg 5 voorgestelde parameters toe
Waaronder: 1, 2, ...
OOjs UI-pictogram menu.svg 1 1
OOjs UI-pictogram menu.svg 2 2
OOjs UI-pictogram menu.svg Voornaam Vorname
OOjs UI-pictogram menu.svg Achternaam Name
OOjs UI-pictogram menu.svg oud Alter

Parameters toevoegen

Nadat u op de knop hebt geklikt, verschijnt de sjabloondocumentatie-editor die rechts wordt weergegeven, met een lijst van de parameters in de sectie Sjabloonparameters , die kunnen worden geïmporteerd door te klikken op Voorgestelde parameters toevoegen , die vervolgens allemaal worden weergegeven zoals rechts weergegeven.

De afzonderlijke secties zijn:

taal
Dit kan worden gebruikt om de documentatietaal van de sjabloon te wijzigen door een nieuwe toe te voegen door op Taal toevoegen te klikken of door een bestaande uit de keuzelijst te selecteren. Over het algemeen is dit echter niet nodig en moet het in het Duits worden achtergelaten.
Sjabloonbeschrijving (de)
In deze sectie moet een korte beschrijving van één regel van de sjabloon worden ingevoerd, die vervolgens in de VisualEditor naast de respectieve sjabloonnaam wordt vermeld.
Voorgestelde opmaak van wikitekst
Hier kunt u definiëren hoe de parameters in de brontekst moeten verschijnen. Mogelijke opties zijn inline (achter elkaar), blok (onder elkaar) of door de gebruiker gedefinieerd (gemengd).
Sjabloonparameters
Deze belangrijkste sectie geeft een overzicht van alle gevonden parameters en hun korte beschrijvingen, indien van toepassing. Met een klik op de betreffende parameter, of in het geval van een nieuw TemplateData-element, moet de aanvullende informatie (metadata) van de parameters worden toegevoegd. Een ander formulier verschijnt zoals hieronder weergegeven.
Volgorde van parameters
Alle gevonden parameters worden hier vermeld en hun volgorde wordt uitgevoerd. Bij het importeren van parameters kan de volgorde worden verwisseld en kan nu worden gecorrigeerd met slepen en neerzetten . De volgorde beïnvloedt niet alleen de lijst van de parameters in de sjabloonvorm van de VisualEditor, maar ook hoe deze in de uiteindelijke brontekst wordt geschreven. De volgorde van de parameters moet daarom altijd overeenkomen met die van eventuele voorbeelden, kopieerfragmenten enz. van de respectieve sjabloondocumentatie.
Parameters toevoegen
Aan het einde van het formulier is er nog een knop waarmee verdere parameters kunnen worden toegevoegd als de automatische import deze over het hoofd heeft gezien of de sjabloon vervolgens is aangevuld met verdere parameters.
Gebruik maken van
Pas wijzigingen toe en voer het TemplateData-element uit.

Stap 3: beschrijf parameters

Editor voor sjabloondocumentatie
Afgewerkt

Achternaam
Aliassen (gescheiden door komma's)
Benaming (de)
Beschrijving (de)
Voorbeeld (de)
Type
OOjs UI-pictogram expand.svg onbekend
Voorgestelde waarden
een boek OOjs UI-indicator clear.svg
| Waarde toevoegen
Standaard (de)

0
auto waarde
Verouderd 0
Noodzakelijk 0
voorgesteld 0

Parameterinformatie verwijderen

Het sjabloonparameterformulier heeft de volgende velden wanneer u op een van de parameters klikt:

Achternaam
Geeft de primaire naam van de parameter aan, dwz de naam die aan het einde moet worden uitgevoerd. Niet-benoemde parameters krijgen een nummer dat hun positie in de sjabloon aangeeft.
Aliassen
Geeft de alternatieve namen van de parameter weer, waarbij elk item wordt gescheiden door een komma. Opmerking: Als de parameters automatisch zijn geïmporteerd, worden er ook vermeldingen gemaakt voor alternatieve namen in het vorige formulier, omdat het importmechanisme niet kan herkennen of een parameternaam een ​​alternatieve naam of een onafhankelijke parameter is. Deze onjuiste parameterinvoeren moeten in dit formulier worden verwijderd door op de knop Parameterinformatie verwijderen aan het einde van het formulier te klikken en hun namen moeten worden ingevoerd in het aliassenveld van de juiste parameterinvoer.
aanwijzing
Als de functie niet automatisch kan worden afgeleid uit de parameternaam, kan hier een meer begrijpelijke aanduiding worden opgegeven, die in de VisualEditor moet worden gebruikt.
Beschrijving
Een beschrijving van de functie van de parameter. Opmerking: de beschrijving ondersteunt geen Wikitext-taalelementen zoals links, opmaak, enz., dus deze moeten worden weggelaten.
voorbeeld
In dit veld kan een voorbeeldwaarde worden opgegeven, die in eerste instantie wordt weergegeven in de VisualEditor als de parameters nog leeg zijn, zodat de sjabloongebruiker kan zien hoe een geldige invoer eruit moet zien.
Type
Het datatype van de parameter kan hier worden gespecificeerd, dat wil zeggen welke waarden de parameter accepteert. De volgende checklist kan worden gebruikt, d.w.z. de parameter staat toe:
  1. Wikitekst, bijv. B. Wikilinks, Opmaak → Inhalt
  2. alleen de naam van een beeldbestand media of zonder voorvoegsel (bijvoorbeeld file:, afbeelding:, ...) → gegevenstype Datei
  3. gebruikersnaam → alleen Benutzer
  4. alleen artikel of andere paginanaam → Seite
  5. alleen nummer, idealiter zonder het scheidingsteken voor duizendtallen en met een punt. als decimaal scheidingsteken → Nummer
  6. alleen datum volgens ISO 8601 , dwz meestal JJJJ-MM-DD → Datum
  7. alleen VorlageVorlage
  8. alleen waarheidswaarde met 0 = nee en 1 = ja → Boolesch
  9. accepteert geen goed gevormde wikitekst, b.v. B. tag sluiten zonder tag openen en vice versa → Unausgeglichener Wikitext
  10. andere enkele regel tekst → Zeile
  11. andere meerregelige tekst → Zeichenfolge
  12. onbekend → Nicht definiert
Voorgestelde waarden
Er kunnen geldige waarden worden opgegeven voor een parameter, die kan worden geselecteerd uit een lijst met suggesties. Waarden kunnen afzonderlijk worden toegevoegd of verwijderd.
Voorbeeldadvertentie: lijst met suggesties
standaard
Hier kunt u aangeven welke waarde impliciet door de sjabloon wordt aangenomen als de parameter niet is ingevuld. Veel Infobox-sjablonen gebruiken bijvoorbeeld de paginatitel als kop of gebruiken hun eigen afbeeldingsformaten (bijvoorbeeld 200px) voor afbeeldingen en hebben een extra parameter waarmee dit gedrag kan worden overschreven. In deze gevallen kan voor deze parameters "Paginatitel" of "200px" worden opgegeven.
auto waarde
Hier kunt u aangeven met welke waarde een nog lege sjabloonparameter moet worden voorgevuld, die dan ook in de brontekst wordt opgeslagen.
Verouderd
Statusparameter , geeft aan of de parameter verouderd is. Als een parameter als verouderd is gemarkeerd, verschijnt er een extra invoerveld waarin kort moet worden aangegeven hoe verder moet, bijv. B. welke parameter moet in plaats daarvan worden gebruikt.
Noodzakelijk
Statusparameter , geeft aan of de parameter absoluut noodzakelijk is om de sjabloon goed te laten werken.
voorgesteld
Statusparameters , Voorgestelde parameters zijn de parameters die worden aanbevolen voor gebruik, dwz de parameters die het vaakst worden gebruikt. Deze worden altijd weergegeven in de VisualEditor en hoeven niet eerst te worden aangevuld en worden altijd aan het einde in de brontekst weergegeven, ook als ze niet zijn ingevuld.
Parameterinformatie verwijderen
Hiermee kan de parameter worden verwijderd. Dit mag alleen worden gedaan als de parameter ofwel volledig uit de sjabloon is verwijderd of een alternatieve naam is voor een bestaande parameter. Parameters die niet langer mogen worden gebruikt en alleen worden ondersteund door de sjabloon om redenen van compatibiliteit, moeten in plaats daarvan als verouderd worden gemarkeerd.
Afgewerkt
Accepteer de wijzigingen en keer terug naar het parameteroverzicht.

Stap 4: Wijzigingen toepassen

Nadat alle parameters zijn beschreven, kunt u in het hoofdformulier op Toepassen klikken, waarna het element TemplateData wordt aangemaakt. Als de sjabloon een documentatiepagina heeft en u het TemplateData-element op de sjabloonpagina hebt gemaakt zoals hierboven beschreven, kopieer dan het element naar de documentatiepagina en negeer de wijzigingen op de sjabloonpagina.

Na het wijzigen van de inhoud van de informatie kunt u optioneel een nul-edit doen op de sjabloonpagina zodat deze ook direct in de cache wordt bijgewerkt en de metadata zo snel mogelijk voor alle tools beschikbaar is.

Structuur van het TemplateData-object

Zie hulp: TemplateData / JSON .

Gereedschappen en hulpmiddelen

Het gebruik van TemplateData in deze Wikipedia is vastgelegd onder:

Generatoren

Als alternatief voor de ingebouwde sjabloondocumentatie-editor :

Als de problemen aanhouden, helpt de technische werkplaats .

internationalisering

Voor sjablonen die in het hele project worden gebruikt, kan het object TemplateData als Commons-gegevensrecord worden opgeslagen onder Data:Templatedata/<Vorlagenname>.tab (zonder de punthaken) en vervolgens als volgt in de betreffende taalversies worden geïntegreerd:

 {{#invoke: TNT | doc | sjabloonnaam}}

De juiste vertaling wordt automatisch uitgevoerd. Sjablonen die nog niet in een taal zijn vertaald, kunnen ook dienovereenkomstig worden bewerkt op Commons.

De documentatie voor {{ Graph: Lines }} is beschikbaar onder commons: Data: Templatedata / Graph: Lines.tab in verschillende talen en is hier geïntegreerd via {{#invoke:TNT|doc|Graph:Lines}} .

De sjabloon die hier wordt gebruikt, gaat ook op precies dezelfde manier te werk : TemplateData - dit kan ook worden gebruikt om wereldwijd gedeelde meertalige definities centraal op te slaan. De documentatie voor de sjabloon: Interwiki-redirect komt van commons: Data: TemplateData / Soft redirect.tab en zou voor ons ook in het Italiaans worden weergegeven - wat TNT niet kan.

anderen

Het gebruik van TemplateData begon wereldwijd in de vroege zomer van 2013.

Voor technische details voor programmeurs zie Help: TemplateData / JSON #Other .

Indien u wensen heeft, kunt u deze communiceren of laten communiceren via Phabricator . Hetzelfde geldt voor bugrapporten.

Extra informatie

MediaWiki: Technische documentatie (Engels) - Gratis Wiki-software (Engels)
Phabricator - Werkbord: #templatedata - Status met lijst met bekende bugs en verzoeken om functionaliteitsuitbreiding (Engels)