wunderbar

Wunderbar: Einfache HTML5-Anwendungen

Wunderbar macht es einfach, gültiges HTML5, wohlgeformtes XHTML, Unicode (utf-8), konsistent eingerückte, lesbare Anwendungen zu erstellen.

Wunderbar wurde von Jim Weirichs Builder inspiriert und stellt die Element-ID- und Klassen-ID-Syntax bereit und basiert auf der Implementierung von Markaby.

Die JSON-Unterstützung von Wunderbar ist vom jbuilder von David Heinemeier Hansson inspiriert.

Ein Tutorial ist in der Entwicklung.

Zusätzliche Funktionalität wird durch Erweiterungen bereitgestellt.

Überblick

Die Prämisse von Wunderbar ist, dass Ausgaben verschiedener Art typischerweise durch das Anhängen einer Reihe von Schlüssel/Wert-Paaren oder einfacher Werte gebildet werden und dass diese Vorgänge dafür optimiert werden sollten. Das Anhängen eines Schlüssel/Wert-Paares erfolgt über:

 _key value

... und das Anhängen eines einfachen Werts erfolgt folgendermaßen:

 _ value

Für HTML werden Schlüssel/Werte für Elementknoten und einfache Werte für Textknoten verwendet. Bei JSON werden Schlüssel/Werte für Hashes und einfache Werte für Arrays verwendet. Für Text werden einfache Werte über Puts ausgegeben und Schlüssel/Wert-Paare werden nicht verwendet.

Die Verschachtelung erfolgt mithilfe von Blöcken.

Wenn der Unterstrichmethode keine Argumente übergeben werden, gibt sie ein Objekt zurück, das zum Ausführen einer Reihe spezieller Funktionen verwendet werden kann. Einige dieser Funktionen gelten nur für die Ausgabemethode. Andere wie Protokollierungsmethoden sind üblich.

Wenn die Unterstrichmethode mehrere Argumente oder eine Kombination aus Argumenten und einem Block übergeben wird, kann sie je nach Typ der übergebenen Argumente andere allgemeine Funktionen ausführen.

Fragezeichen, Ausrufezeichen und Unterstriche als Suffixe im Methodennamen können die Ergebnisse verändern.

Schnellstart (HTML)

Einfaches Element:

 _br

Verschachtelte Elemente:

 _div do
  _hr
end

Element mit Text:

 _h1 "My weblog"

Element mit Attributen:

 _img src: '/img/logo.jpg', alt: 'site logo'

Element mit Text und Attributen:

 _a 'search', href: 'http://google.com'

Element mit booleschen Attributen:

 _input 'Cheese', type: 'checkbox', name: 'cheese', checked: true

Element mit booleschen Attributen (alternative Form):

 _input 'Cheese', :checked, type: 'checkbox', name: 'cheese'

Element mit optionalen (weggelassenen) Attributen:

 _tr class: nil

Text (Markup-Zeichen werden maskiert):

 _ "<3"

Text (kann Markup enthalten):

 _{"<em>hello</em>!!!"}

Import von HTML/XML:

 _[Nokogiri::XML "<em>hello</em>"]

Gemischter Inhalt (Autospaced):

 _p do
  _ 'It is a'
  _em 'very'
  _ 'nice day.'
end

Gemischter Inhalt (platzgesteuert):

 _p! do
  _ 'Source is on '
  _a 'github', href: 'https://github.com/'
  _ '.'
end

Fügen Sie im erzeugten HTML-Code Leerzeilen zwischen den Zeilen ein:

 _tbody do
  _tr_ do
    _td 1
  end
  _tr_ do
    _td 2
  end
  _tr_ do
    _td 3
  end
end

Ausnahmen erfassen:

 _body? do
  raise NotImplementedError.new('page')
end

Klassenattribut-Verknüpfung (entspricht class="front"):

 _div.front do
end

Verknüpfung für ID-Attribute (entspricht id="search"):

 _div.search! do
end

Komplette Listen/Zeilen können über Arrays definiert werden:

 _ul %w(apple orange pear)
_ol %w(apple orange pear)
_table do
  _tr %w(apple orange pear)
end

Über Enumerables kann eine beliebige Iteration durchgeführt werden:

 _dl.colors red: '#F00', green: '#0F0', blue: '#00F' do |color, hex|
  _dt color.to_s
  _dd hex
end

Grundlegende Schnittstelle

Ein typisches Hauptprogramm erzeugt eine oder mehrere HTML-, JSON- oder Nur-Text-Ausgaben. Dies wird durch die Bereitstellung eines oder mehrerer der folgenden Elemente erreicht:

 _html do
  code
end

_xhtml do
  code
end

_json do
  code
end

_text do
  code
end

_websocket do
  code
end

In jedem kann beliebiger Ruby-Code platziert werden. Formularparameter werden als Instanzvariablen zur Verfügung gestellt (z. B. @name ). Auf Werte der Hostumgebung (CGI, Rack, Sinatra) kann als Methoden des _ Objekts zugegriffen werden: zum Beispiel _.headers (CGI), _.set_cookie (Rack), _.redirect (Sinatra).

Verwenden Sie zum Anhängen an die erzeugte Ausgabe die unten beschriebenen _ Methoden. Beispielanwendungen finden Sie im Tutorial.

Für Wunderbar.html bereitgestellte Methoden

Durch den Aufruf von Methoden, die mit einem Unicode-Low-Line-Zeichen („_“) beginnen, wird ein HTML-Tag generiert. Wie der Builder, auf dem diese Bibliothek basiert, können diese Tags Textinhalte und Attribute haben. Tags können auch verschachtelt werden. Logik kann frei gemischt werden.

Wunderbar weiß, welche HTML-Tags explizit mit separaten End-Tags geschlossen werden müssen (Beispiel: textarea ) und welche niemals mit separaten End-Tags geschlossen werden sollten (Beispiel: br ). Es kümmert sich auch um HTML-Anführungszeichen und Escapezeichen für Argumente und Text.

Suffixe nach dem Tag-Namen ändern die Verarbeitung.

• ! : Deaktiviert alle speziellen Verarbeitungen, einschließlich Einrückungen
• ? : Fügt Code hinzu, um Ausnahmen zu retten und Tracebacks zu erstellen
• _ : Fügt zusätzliche Leerzeilen zwischen diesem Tag und den Geschwistern hinzu

Die Methode „ _ “ dient mehreren Zwecken. Wenn Sie es mit einem einzelnen Argument aufrufen, wird Markup eingefügt, wobei die Einrückung berücksichtigt wird. Das Einfügen von Markup ohne Berücksichtigung der Einrückung erfolgt mit „ _ << text “. Eine Reihe weiterer Convenience-Methoden sind definiert:

• _ : Text mit Einrückung einfügen, die der aktuellen Ausgabe entspricht
• _! : Text ohne Einzug einfügen
• _.post? – Wurde dies über HTTP POST aufgerufen?
• _.system – ruft einen Shell-Befehl auf, erfasst stdin, stdout und stderr
• _.submit – führt Befehl (oder Block) als Deamon-Prozess aus
• _.xhtml? --Ausgabe als XHTML?

Die _.system -Methode verwendet einen optionalen Hash als letzten Parameter. Dies kann verwendet werden, um Einstellungen für die zugrunde liegende Process.spawn-Methode bereitzustellen. Beispiel: ._system('pwd',{ system_opts: { chdir: dir } , system_env: { 'FOO' => 'BAR' } }) Beachten Sie, dass Umgebungsvariablennamen als Zeichenfolgen und nicht als Symbole bereitgestellt werden müssen. Zu den weiteren Optionen, die mit _.system verwendet werden können, gehören:

• :tag – das HTML-Tag, das für die Eingabe/Ausgabe verwendet werden soll; Standardmäßig ist pre
• :bundlelines – ob alle Zeilen für einen bestimmten Ausgabetyp (stderr, stdout usw.) als Teil eines einzelnen Tags verarbeitet werden sollen. Wenn nicht angegeben, wird für pre -Tags standardmäßig true und andernfalls false verwendet. Bei false wird jede Ausgabezeile separat verarbeitet.

Auf diese Weise kann auf alle vom Builder definierten Methoden (normalerweise enden diese mit einem Ausrufezeichen) und alle Methoden des Wunderbar-Moduls zugegriffen werden. Beispiele:

• _.tag! :foo : Elemente einfügen, bei denen der Name dynamisch sein kann
• _.comment! "text" : Kommentar hinzufügen
• _.error 'Log message' : Schreiben Sie eine Nachricht in das Serverprotokoll

Unterstriche in Element- und Attributnamen werden in Bindestriche umgewandelt. Um dieses Verhalten zu deaktivieren, drücken Sie Attributnamen als Zeichenfolgen aus und verwenden Sie das _.tag! Methode für Elementnamen.

XHTML unterscheidet sich von HTML durch das Escapen von Inline-Stil- und Skriptelementen. XHTML greift auch auf die HTML-Ausgabe zurück, es sei denn, der Benutzeragent gibt über den HTTP-Accept-Header an, dass es XHTML unterstützt.

Zusätzlich zur Standardverarbeitung von Elementen, Text und Attributen definiert Wunderdar zusätzliche Verarbeitung für Folgendes:

• _head : Meta-Zeichensatz utf-8 einfügen
• _svg : SVG-Namespace einfügen
• _math : Mathe-Namespace einfügen
• _coffeescript : Coffeescript in JS konvertieren und Skript-Tag einfügen

Beachten Sie, dass das Hinzufügen eines Ausrufezeichens am Ende des Tag-Namens dieses Verhalten deaktiviert.

Wenn eines der in der _html Deklaration übergebenen Attribute :_width ist, wird versucht, den Text so umzufließen, dass diese Zeilenbreite nicht überschritten wird. Dies wird nicht durchgeführt, wenn dadurch die tatsächliche Anzeige beeinträchtigt wird.

Wenn keines der untergeordneten Elemente für das html -Element head oder body ist, werden diese Tags für Sie erstellt und die relevanten untergeordneten Elemente werden in den entsprechenden Abschnitt verschoben. Wenn der Text ein h1 Element enthält und der head keinen title enthält, wird ein Titelelement basierend auf dem Text erstellt, der dem ersten h1 Element bereitgestellt wird.

Für Wunderbar.json bereitgestellte Methoden

Übliche Operationen bestehen darin, einen Hash oder ein Array von Werten zurückzugeben. Hashes sind eine Reihe von Name/Wert-Paaren und Arrays sind eine Reihe von Werten.

 Wunderbar . json do
  _content format_content ( @message . content )
  _ @message , :created_at , :updated_at 

  _author do
    _name @message . creator . name . familiar
    _email_address @message . creator . email_address_with_name
    _url url_for ( @message . creator , format : :json )
  end

  if current_user . admin?
    _visitors calculate_visitors ( @message )
  end

  _comments @message . comments , :content , :created_at
  
  _attachments @message . attachments do | attachment |
    _filename attachment . filename
    _url url_for ( attachment )
  end
end

Durch Aufrufen von Methoden, die mit einem Unicode-Low-Line-Zeichen („_“) beginnen, wird diesem Hash ein Schlüssel/Wert-Paar hinzugefügt. Hashes können auch verschachtelt werden. Logik kann frei gemischt werden.

Die Methode „ _ “ dient mehreren Zwecken.

• Wenn Sie es mit mehreren Argumenten aufrufen, wird das erste Argument als Objekt und der Rest als zu extrahierende Attribute behandelt

  • Beispiel: _ File.stat('foo'), :mtime, :size, :mode

• Wenn Sie es mit einem einzelnen Enumerable-Objekt und einem Block aufrufen, wird ein Array zurückgegeben, das auf der Zuordnung jedes Einwands aus der Aufzählung zum Block basiert

  • Beispiel: _([1,2,3]) {|n| n*n}

• Arrays können auch mit der _ -Methode erstellt werden:

    _ 1
    _ 2
  

Die _ Methode gibt einen Proxy an das zu erstellende Objekt zurück. Dies ist oft praktisch, wenn der Aufruf ohne Argumente erfolgt. Beispiele:

    _.sort!
    _['foo'] = 'bar'

Für Wunderbar.text bereitgestellte Methoden

Das Anhängen an den Ausgabestream erfolgt mit der Methode _ , die puts entspricht. Die _ Methode gibt ein Objekt zurück, das als Proxy für den Ausgabestream dient und Zugriff auf andere nützliche Methoden bietet, zum Beispiel:

    _.print 'foo'
    _.printf "Hello %s!n", 'world'

Für Wunderbar.websocket bereitgestellte Methoden

Für die WebSocket-Unterstützung muss em-websocket installiert sein.

Ein Web-Socket ist ein bidirektionaler Kanal. Mit _.send oder _.push können beliebige Strings versendet werden. Üblicherweise können alle oben beschriebenen JSON-Array-Methoden verwendet werden. Der wichtige Unterschied besteht darin, dass die einzelnen Einträge einzeln gesendet und so erzeugt werden, wie sie erzeugt werden.

_.recv oder _.pop können beliebige Strings empfangen werden. Häufiger wird _.subscribe verwendet, um einen Block zu registrieren, der als Rückruf verwendet wird.

_.system führt einen beliebigen Befehl aus. Ausgabezeilen werden über den Websocket gesendet, während sie als JSON-codierte Hashes mit zwei Werten empfangen werden: type ist einer von stdin , stdout oder stderr ; und line , die die Zeile selbst enthält. Wenn der Befehl ein Array ist, werden die Elemente des Arrays als Shell-Befehlsargumente maskiert. Verschachtelte Arrays können verwendet werden, um Elemente vor der Echoausgabe des Befehls an stdin zu verbergen. Nullwerte werden weggelassen.

Optionen für _websocket werden als Hash bereitgestellt:

• :port wählt eine Portnummer aus, wobei standardmäßig eine verfügbare für Sie ausgewählt wird.
• :sync auf false gesetzt ist, wird der WebSocket-Server als Daemon-Prozess ausgeführt. Der Standardwert ist „ true , wenn es über die Befehlszeile ausgeführt wird, und „ false wenn es als CGI ausgeführt wird.
• buffer_limit begrenzt die Anzahl der Einträge, die bei offenen Anfragen beibehalten und an neue Clients gesendet werden. Der Standardwert ist 1 . Ein Wert von Null deaktiviert die Pufferung. Ein Wert von nil führt zu unbegrenzter Pufferung. Hinweis: Die Pufferung ist praktisch unbegrenzt, bis der erste Client eine Verbindung herstellt.

Standardmäßig sicher

Wunderbar maskiert alle HTML- und JSON-Ausgaben ordnungsgemäß und beseitigt so Probleme bei der HTML- oder JavaScript-Injection. Dazu gehören Aufrufe von _ zum direkten Einfügen von Text. Sofern nokogiri nicht zuvor erforderlich war (siehe optionale Abhängigkeiten unten), werden Aufrufe zum Einfügen von Markup ( _{...} ) dem Markup entkommen.

Globals bereitgestellt

• $USER – Host-Benutzer-ID
• $PASSWORD – Host-Passwort (wenn CGI und HTTP_AUTHORIZATION durchgereicht werden)
• $HOME – Home-Verzeichnis
• $SERVER – Servername
• $HOME – Home-Verzeichnis des Benutzers
• $HOST – Server-Host

Außerdem werden die folgenden Umgebungsvariablen festgelegt, sofern dies noch nicht geschehen ist:

• HOME
• HTTP_HOST
• LANG
• REMOTE_USER

Schließlich werden die standardmäßigen externen und internen Kodierungen auf UTF-8 eingestellt.

Protokollierung

• _.debug : Debug-Meldungen
• _.info : Informationsnachrichten
• _.warn : Warnmeldungen
• _.error : Fehlermeldungen
• _.fatal : Schwerwiegende Fehlermeldungen
• _.log_level =: Protokollierungsstufe festlegen (Standard: :warn )
• _.default_log_level =: Protokollebene festlegen, aber nicht überschreiben
• _.logger : Logger-Instanz zurückgeben

Befehlszeilenoptionen

Bei der Ausführung über die Befehlszeile können CGI-Name=Wert-Paare angegeben werden. Darüber hinaus werden folgende Optionen unterstützt:

• --get : HTML-Ausgabe (HTTP GET) wird erwartet
• --post : HTML-Ausgabe (HTTP POST) wird erwartet
• --json : JSON-Ausgabe (XML HTTP Request) wird erwartet
• --html : HTML-Ausgabe erzwingen
• --prompt oder --offline : Eingabeaufforderung für Schlüssel/Wert-Paare mithilfe von stdin
• --debug , --info , --warn , --error , --fatal : Protokollebene festlegen
• --install= Pfad: Erstellt ein über Suexec aufrufbares Wrapper-Skript
• --rescue oder --backtrace bewirken, dass das Wrapper-Skript Fehler erfasst

Optionale Abhängigkeiten

Abhängig davon, welche Funktionen Sie verwenden, werden die folgenden Edelsteine ​​benötigt:

• em-websocket wird von wunderbar/websocket benötigt
• kramdown wird von wunderbar/markdown benötigt
• ruby2js fügt Unterstützung für als Blöcke geschriebene Skripte hinzu
• sourcify wird von wunderbar/opal benötigt

Die folgenden Gems sind für gleichnamige Erweiterungen erforderlich:

• coderay – Syntaxhervorhebung
• opal – Ruby-zu-Javascript-Compiler
• rack - Webserver-Schnittstelle
• sinatra - DSL zum Erstellen von Webanwendungen

Die folgenden Gems führen, wenn sie installiert sind, zu einer saubereren und schöneren Ausgabe:

• nokogiri bereinigt HTML-Fragmente, die über << und _{} eingefügt wurden.
• nokogumbo bereinigt auch HTML-Fragmente, die über << und _{} eingefügt wurden. Wenn dieser Edelstein verfügbar ist, wird er der direkten Verwendung von nokogiri vorgezogen.
• escape einer schöneren Zitierung von system

Verwandte Bemühungen

• Baumeister
• JBuilder
• Markaby
• Nokogiri::HTML::Builder
• Tagz