wunderbar

Wunderbar : applications HTML5 faciles

Wunderbar facilite la production d'applications HTML5 valides, XHTML bien formées, Unicode (utf-8), uniformément indentées et lisibles.

Wunderbar a été inspiré par le Builder de Jim Weirich et fournit la syntaxe de l'identifiant d'élément et de l'identifiant de classe et est basé sur l'implémentation de Markaby.

Le support JSON de Wunderbar est inspiré du jbuilder de David Heinemeier Hansson.

Un tutoriel est en cours de développement.

Des fonctionnalités supplémentaires sont fournies par les extensions.

Aperçu

Le principe de Wunderbar est que les sorties de différents types sont généralement formées en ajoutant soit une série de paires clé/valeur, soit des valeurs simples, et ces opérations doivent être optimisées pour. L'ajout d'une paire clé/valeur se fait via :

 _key value

... et l'ajout d'une valeur simple se fait ainsi :

 _ value

Pour HTML, la clé/valeur est utilisée pour les nœuds d'élément et les valeurs simples sont utilisées pour les nœuds de texte. Pour JSON, la clé/valeur est utilisée pour les hachages et les valeurs simples sont utilisées pour les tableaux. Pour le texte, les valeurs simples sont générées via des put et les paires clé/valeur ne sont pas utilisées.

L'imbrication s'effectue à l'aide de blocs.

La méthode de soulignement, lorsqu'elle ne reçoit aucun argument, renvoie un objet qui peut être utilisé pour exécuter un certain nombre de fonctions spéciales. Certaines de ces fonctions sont propres à la méthode de sortie. D'autres, comme les méthodes de journalisation, sont courantes.

La méthode de soulignement, lorsqu'elle est transmise à plusieurs arguments ou à une combinaison d'arguments et d'un bloc, peut exécuter d'autres fonctions courantes, en fonction des types d'arguments transmis.

Les suffixes de point d'interrogation, d'exclamation et de trait de soulignement dans le nom de la méthode peuvent modifier les résultats.

Démarrage rapide (HTML)

Élément simple :

 _br

Éléments imbriqués :

 _div do
  _hr
end

Élément avec texte :

 _h1 "My weblog"

Élément avec attributs :

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

Élément avec à la fois du texte et des attributs :

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

Élément avec des attributs booléens :

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

Élément avec des attributs booléens (forme alternative) :

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

Élément avec des attributs facultatifs (omis) :

 _tr class: nil

Texte (les caractères de balisage sont échappés) :

 _ "<3"

Texte (peut contenir des balises) :

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

Importation de HTML/XML :

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

Contenu mixte (espacement automatique) :

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

Contenu mixte (espace contrôlé) :

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

Insérez des lignes vides entre les lignes dans le code HTML produit :

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

Capturer les exceptions :

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

Raccourci d'attribut de classe (équivalent à class="front") :

 _div.front do
end

Raccourci des attributs d'identifiant (équivalent à id="search") :

 _div.search! do
end

Des listes/lignes complètes peuvent être définies à l'aide de tableaux :

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

Une itération arbitraire peut être effectuée sur les Enumerables :

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

Interface de base

Un programme principal typique produit une ou plusieurs sorties HTML, JSON ou texte brut. Ceci est accompli en fournissant un ou plusieurs des éléments suivants :

 _html do
  code
end

_xhtml do
  code
end

_json do
  code
end

_text do
  code
end

_websocket do
  code
end

Du code Ruby arbitraire peut être placé dans chacun. Les paramètres du formulaire sont mis à disposition sous forme de variables d'instance (par exemple, @name ). Les valeurs de l'environnement hôte (CGI, Rack, Sinatra) sont accessibles en tant que méthodes de l'objet _ : par exemple _.headers (CGI), _.set_cookie (Rack), _.redirect (Sinatra).

Pour ajouter à la sortie produite, utilisez les méthodes _ décrites ci-dessous. Des exemples d'applications se trouvent dans le didacticiel.

Méthodes fournies à Wunderbar.html

L'appel de méthodes commençant par un caractère de ligne basse Unicode ("_") générera une balise HTML. Comme pour le constructeur sur lequel est basée cette bibliothèque, ces balises peuvent avoir du contenu et des attributs textuels. Les balises peuvent également être imbriquées. La logique peut être librement mélangée.

Wunderbar sait quelles balises HTML doivent être explicitement fermées avec des balises de fin distinctes (exemple : textarea ) et lesquelles ne doivent jamais être fermées avec des balises de fin distinctes (exemple : br ). Il s'occupe également des citations HTML et de l'échappement des arguments et du texte.

Les suffixes après le nom de la balise modifieront le traitement.

• ! : désactive tous les traitements spéciaux, y compris l'indentation
• ? : ajoute du code pour sauver les exceptions et produire des traçages
• _ : ajoute des lignes vides supplémentaires entre cette balise et les frères et sœurs

La méthode " _ " répond à plusieurs objectifs. L'appeler avec un seul argument insère un balisage, en respectant l'indentation. L'insertion d'un balisage sans tenir compte de l'indendatation se fait en utilisant " _ << text ". Un certain nombre d'autres méthodes pratiques sont définies :

• _ : insérer du texte avec une indentation correspondant à la sortie actuelle
• _! : insérer du texte sans retrait
• _.post? -- cela a-t-il été invoqué via HTTP POST ?
• _.system -- appelle une commande shell, capture stdin, stdout et stderr
• _.submit -- exécute la commande (ou le bloc) en tant que processus démon
• _.xhtml? -- afficher en XHTML ?

La méthode _.system prend un hachage facultatif comme dernier paramètre. Cela peut être utilisé pour fournir des paramètres pour la méthode Process.spawn sous-jacente. Par exemple : ._system('pwd',{ system_opts: { chdir: dir } , system_env: { 'FOO' => 'BAR' } }) Notez que les noms de variables d'environnement doivent être fournis sous forme de chaînes et non de symboles. Les options supplémentaires pouvant être utilisées avec _.system incluent :

• :tag - la balise HTML à utiliser pour l'entrée/sortie ; par défaut, pre
• :bundlelines - s'il faut traiter toutes les lignes pour un type de sortie donné (stderr, stdout, etc.) dans le cadre d'une seule balise. S'il n'est pas spécifié, la valeur par défaut est true pour les balises pre et false dans le cas contraire. Si false , chaque ligne de sortie est traitée séparément.

L'accès à toutes les méthodes définies par le constructeur (généralement celles-ci se terminent par un point d'exclamation) et à toutes les méthodes du module Wunderbar est accessible de cette manière. Exemples :

• _.tag! :foo : insère des éléments dont le nom peut être dynamique
• _.comment! "text" : ajouter un commentaire
• _.error 'Log message' : écrire un message dans le journal du serveur

Les traits de soulignement dans les noms d'éléments et d'attributs sont convertis en tirets. Pour désactiver ce comportement, exprimez les noms d'attribut sous forme de chaînes et utilisez le _.tag! méthode pour les noms d’éléments.

XHTML diffère du HTML par l'échappement des éléments de style et de script en ligne. XHTML reviendra également à la sortie HTML à moins que l'agent utilisateur n'indique qu'il prend en charge XHTML via l'en-tête HTTP Accept.

En plus du traitement par défaut des éléments, du texte et des attributs, Wunderdar définit un traitement supplémentaire pour les éléments suivants :

• _head : insérer le méta charset utf-8
• _svg : insérer un espace de noms svg
• _math : insérer un espace de noms mathématique
• _coffeescript : convertissez coffeescript en JS et insérez une balise de script

Notez que l'ajout d'un point d'exclamation à la fin du nom de la balise désactive ce comportement.

Si l'un des attributs transmis dans la déclaration _html est :_width , une tentative sera faite pour redistribuer le texte afin de ne pas dépasser cette largeur de ligne. Cela ne sera pas fait si cela affecte ce qui est réellement affiché.

Si aucun des éléments enfants de l'élément html n'est head ou body , alors ces balises seront créées pour vous et les enfants concernés seront déplacés vers la section appropriée. Si le body contient un élément h1 et que le head ne contient pas de title , un élément title sera créé en fonction du texte fourni au premier élément h1 .

Méthodes fournies à Wunderbar.json

Les opérations courantes consistent à renvoyer un hachage ou un tableau de valeurs. Les hachages sont une série de paires nom/valeur et les tableaux sont une série de valeurs.

 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

L'appel de méthodes commençant par un caractère de ligne basse Unicode ("_") ajoutera une paire clé/valeur à ce hachage. Les hachages peuvent également être imbriqués. La logique peut être librement mélangée.

La méthode " _ " répond à plusieurs objectifs.

• l'appeler avec plusieurs arguments fera que le premier argument sera traité comme l'objet et le reste comme les attributs à extraire

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

• l'appeler avec un seul objet Enumerable et un bloc entraînera le retour d'un tableau basé sur le mappage de chaque objection de l'énumération avec le bloc

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

• les tableaux peuvent également être construits à l'aide de la méthode _ :

    _ 1
    _ 2
  

La méthode _ renvoie un proxy à l'objet en cours de construction. C'est souvent pratique lorsqu'il est appelé sans argument. Exemples :

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

Méthodes fournies à Wunderbar.text

L'ajout au flux de sortie s'effectue à l'aide de la méthode _ , qui équivaut à puts . La méthode _ renvoie un objet qui proxy le flux de sortie, qui donne accès à d'autres méthodes utiles, par exemple :

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

Méthodes fournies à Wunderbar.websocket

La prise en charge de WebSocket nécessite l'installation em-websocket .

Une socket Web est un canal bidirectionnel. _.send ou _.push peuvent être utilisés pour envoyer des chaînes arbitraires. Plus communément, les méthodes de tableau JSON décrites ci-dessus peuvent toutes être utilisées, la différence importante est que les entrées individuelles sont envoyées individuellement et au fur et à mesure de leur production.

_.recv ou _.pop peuvent être utilisés pour recevoir des chaînes arbitraires. Plus communément, _.subscribe est utilisé pour enregistrer un bloc utilisé comme rappel.

_.system exécutera une commande arbitraire. Les lignes de sortie sont envoyées via le websocket lorsqu'elles sont reçues sous forme de hachages codés JSON avec deux valeurs : type est l'un des stdin , stdout ou stderr ; et line qui contient la ligne elle-même. Si la commande est un tableau, les éléments du tableau seront échappés en tant qu'arguments de commande Shell. Les tableaux imbriqués peuvent être utilisés pour masquer les éléments de l'écho de la commande vers stdin. Les valeurs nulles sont omises.

Les options de _websocket sont fournies sous forme de hachage :

• :port choisira un numéro de port, la valeur par défaut étant qu'un numéro disponible soit choisi pour vous.
• :sync défini sur false entraînera l'exécution du serveur WebSocket en tant que processus démon. La valeur par défaut est true lorsqu'elle est exécutée à partir de la ligne de commande et false lorsqu'elle est exécutée en tant que CGI.
• buffer_limit limitera le nombre d'entrées conservées et envoyées aux nouveaux clients sur les demandes ouvertes. La valeur par défaut est 1 . Une valeur de zéro désactivera la mise en mémoire tampon. Une valeur nil entraînera une mise en mémoire tampon illimitée. Remarque : la mise en mémoire tampon est effectivement illimitée jusqu'à ce que le premier client se connecte.

Sécurisé par défaut

Wunderbar échappera correctement à toutes les sorties HTML et JSON, éliminant ainsi les problèmes d'injection HTML ou JavaScript. Cela inclut les appels à _ pour insérer du texte directement. Sauf si nokogiri était auparavant requis (voir les dépendances facultatives ci-dessous), les appels à insérer un balisage ( _{...} ) échapperont au balisage.

Globals fournis

• $USER - ID utilisateur de l'hôte
• $PASSWORD - Mot de passe de l'hôte (si CGI et HTTP_AUTHORIZATION sont transmis)
• $HOME - Répertoire personnel
• $SERVER - Nom du serveur
• $HOME - répertoire personnel de l'utilisateur
• $HOST - hôte du serveur

De plus, les variables d'environnement suivantes sont définies si elles ne le sont pas déjà :

• HOME
• HTTP_HOST
• LANG
• REMOTE_USER

Enfin, les encodages externes et internes par défaut sont définis sur UTF-8.

Enregistrement

• _.debug : messages de débogage
• _.info : messages d'information
• _.warn : messages d'avertissement
• _.error : messages d'erreur
• _.fatal : messages d'erreur fatals
• _.log_level = : définir le niveau de journalisation (par défaut : :warn )
• _.default_log_level = : définir, mais ne pas remplacer, le niveau de journalisation
• _.logger : renvoie l'instance de Logger

Options de ligne de commande

Lorsqu'elles sont exécutées à partir de la ligne de commande, des paires nom=valeur CGI peuvent être spécifiées. De plus, les options suivantes sont prises en charge :

• --get : la sortie HTML (HTTP GET) est attendue
• --post : la sortie HTML (HTTP POST) est attendue
• --json : la sortie JSON (requête HTTP XML) est attendue
• --html : force la sortie HTML
• --prompt ou --offline : demande des paires clé/valeur à l'aide de stdin
• --debug , --info , --warn , --error , --fatal : définir le niveau de journalisation
• --install= chemin : produit un script wrapper appelable par suexec
• --rescue ou --backtrace amène le script wrapper à capturer les erreurs

Dépendances facultatives

Les gemmes suivantes sont nécessaires en fonction des fonctions que vous utilisez :

• em-websocket est requis par wunderbar/websocket
• kramdown est requis par wunderbar/markdown
• ruby2js ajoute la prise en charge des scripts écrits sous forme de blocs
• sourcify est requis par wunderbar/opal

Les gemmes suivantes sont requises par les extensions du même nom :

• coderay - coloration syntaxique
• opal - compilateur Ruby vers Javascript
• rack - interface du serveur Web
• sinatra - DSL pour créer des applications Web

Les gemmes suivantes, si elles sont installées, produiront un résultat plus propre et plus joli :

• nokogiri nettoie les fragments HTML insérés via << et _{} .
• nokogumbo nettoie également les fragments HTML insérés via << et _{} . Si cette gemme est disponible, elle sera préférée à l'utilisation directe de nokogiri .
• escape à des citations plus jolies de commandes system

Efforts connexes

• Constructeur
• JBuilder
• Markaby
• Nokogiri :: HTML :: Constructeur
• Tagz