Yesod (marco de trabajo web)

Yesod utiliza una interfaz de aplicación web (WAI), ^{[ 3 ]} un tipo de interfaz de programación de aplicaciones ( API ), para aislar los servlets , también conocidos como aplicaciones web, de los servidores, con manejadores para los protocolos de servidor Common Gateway Interface (CGI), ^{[ 4 ]} FastCGI , ^{[ 5 ]} Simple Common Gateway Interface (SCGI), ^{[ 6 ]} Warp, ^{[ 7 ]} Launch (abre como URL local en el navegador predeterminado, cerrando el servidor cuando se cierra la ventana), ^{[ 8 ]}

Véase la referencia ^{[ 9 ]} . Yesod requiere un tipo de datos que instancie las clases modelo-vista-controlador . Este se denomina tipo base . En el ejemplo siguiente, se llama "MyApp".

El modelo REST identifica un recurso web mediante una ruta web. En este caso, los recursos REST reciben nombres con el sufijo R (como "HomeR") y se listan en una plantilla de descripción de mapa del sitio de parseRoutes . A partir de esta lista, se derivan los nombres de las rutas y los nombres de los manejadores de despacho.

Yesod utiliza la metaprogramación Template Haskell para generar código a partir de plantillas en tiempo de compilación, asegurando que los nombres en las plantillas coincidan y que todo pase la verificación de tipos (por ejemplo, nombres de recursos web y nombres de manejadores).

Al insertar una llamada mkYesod , se llamarán a las primitivas de Template Haskell para generar el código correspondiente a los miembros del tipo de ruta y las instancias de las clases del controlador de despacho para despachar las llamadas GET a la ruta HomeR a una rutina llamada que las compone ambas como "getHomeR", esperando un manejador existente que coincida con el nombre.

Ejemplo de programa "¡Hola, mundo!" basado en una interfaz de servidor CGI ( Common Gateway Interface ) (los tipos de manejadores han cambiado, pero la filosofía se mantiene):

{- archivo wai-cgi-hello.hs -} {-# LANGUAGE PackageImports, TypeFamilies, QuasiQuotes, MultiParamTypeClasses,  TemplateHaskell, OverloadedStrings #-} import "wai" Network.Wai import "wai-extra" Network.Wai.Handler.CGI ( run ) -- manejador WAI intercambiableimport "yesod" Yesod import "yesod-core" Yesod.Handler ( getRequest ) import "text" Data.Text ( Text ) import "shakespeare" Text.Cassius ( Color ( .. ), colorBlack )-- los datos de tipo Foundation MyApp = MyApp-- plantilla de mapa del sitio, lista de ruta, nombre del recurso y métodos aceptados -- `mkYesod` toma el nombre del tipo de base como parámetro para la composición de nombres de las funciones de despacho mkYesod "MyApp" [ parseRoutes | / HomeR GET | ]instancia Yesod MyApp-- plantilla CSS estructurada con sangría myStyle :: [ Texto ] → CssUrl url myStyle paramStyle = [ cassius | . box border : 1 px solid # { boxColor } | ] donde boxColor = case paramStyle of [ "high-contrast" ] → colorBlack _ → Color 0 0 255-- plantilla HTML estructurada con sangría myHtml :: [( Texto , Texto )] → HtmlUrl url myHtml params = [ hamlet |

<!-- La indentación, o la falta de ella, bajo las etiquetas o comandos iniciales (el prefijo ' $ ')  describe el contenido o la estructura del árbol de secuencia --> <!-- Los prefijos '.' o ' # ' en las etiquetas introducen valores de atributo "class" o "id" con estilo CSS --> <!-- La interpolación de expresiones haskell sigue la sintaxis #{ expr } de las "plantillas shakespeare" --><p> ¡ Hola mundo ! Hay < span.box > #{ length params} parámetros </span> : $ if null params <p> Nada que listar $ else <ul> $ forall param < -params <li> # { fst param } : # { snd param } |] 

getHomeR :: Handler RepHtml getHomeR = do req <- getRequest let params = reqGetParams req paramStyle <- lookupGetParams "style" defaultLayout $ do -- agregando widgets a la mónada Widget (una mónada ''Writer'') setTitle "Ejemplo de Yesod" toWidgetHead $ myStyle paramStyle toWidgetBody $ myHtml params-- existen variantes de la función ''run'' para diferentes manejadores WAIprincipal = toWaiApp MyApp >>= ejecutar

# Prueba CGI export REMOTE_ADDR = 127 .0.0.1 export REQUEST_METHOD = GET export PATH_INFO = / export QUERY_STRING = 'p1=abc;p2=def;style=high-contrast' ./wai-cgi-hello 

^{[ 9 ]}

Véase la referencia ^{[ 10 ] [ 11 ]} Yesod sigue el modelo de transferencia de estado representacional de acceso a documentos web, identificando documentos y directorios como recursos con un constructor Route, nombrado con un sufijo R mayúscula (por ejemplo, HomeR).

La tabla de rutas

La plantilla parseRoutes debe enumerar los recursos especificando las partes de la ruta, el nombre del recurso y los métodos de despacho que se aceptarán.

Es posible capturar segmentos de URL como parámetro especificando el prefijo '#' para la captura de un solo segmento o '*' para la captura de varios segmentos, seguido del tipo de parámetro.

-- dado un tipo de base MyAppmkYesod "MyApp" [ parseRoutes | / HomeR -- no se especifican métodos http: se aceptan todos los métodos / blog BlogR GET POST-- el prefijo '#' especifica el segmento de ruta como un parámetro del controlador de ruta / artículo /# ArticleId ArticleR GET PUT-- el prefijo '*' especifica el parámetro como una secuencia de fragmentos de ruta / rama /* Textos BranchR GET-- para simplificar la gramática, los tipos compuestos deben usar un alias, por ejemplo, type Texts for ''[Text]'' | ]

• Al aplicar la plantilla anterior se generan los siguientes constructores de ruta:

Ruta de datos MyApp = HomeR -- referenciada en plantillas como: @{HomeR} | BlogR -- en plantillas: @{BlogR} | ArticleR ArticleId -- en plantillas: @{ArticleR myArticleId} | BranchR Texts -- en plantillas: @{BranchR myBranchSegments}

• Para cada método HTTP compatible , se debe crear una función controladora que coincida con los nombres de despacho generados por mkYesod a partir de la plantilla parseRoutes , anteponiendo el nombre del método (o el prefijo "handler" si no se especifica ningún método) al recurso, como se describe (los tipos de controladores de las versiones actuales han cambiado, pero la filosofía se mantiene):

-- para "/ HomeR" -- no se especifican métodos http ⇒ solo un manejador con el prefijo ''handler'' handlerHomeR :: HasReps t ⇒ Handler t-- para "/blog BlogR GET POST" getBlogR :: HasReps t ⇒ Handler t postBlogR :: HasReps t ⇒ Handler t-- para "/artículo/#ArticleId ArticleR GET PUT" getArticleR :: HasReps t ⇒ ArticleId → Handler t putArticleR :: HasReps t ⇒ ArticleId → Handler t

Véase la referencia ^{[ 10 ] .}

Véase la referencia ^{[ 12 ]} Complementos de autenticación: OpenID , BrowserID , Email, GoogleEmail, HashDB, RpxNow. ^{[ 13 ]}

Existe una configuración importante para la redirección automática después de la autenticación. ^{[ 14 ]}

Véase la referencia ^{[ 15 ]} Backends de sesión: ClientSession ^{[ 16 ]} (almacena la sesión en una cookie), ServerSession ^{[ 17 ] [ 18 ]} (almacena la mayor parte de los datos de la sesión en el servidor)

Para evitar una sobrecarga de ancho de banda excesiva, los sitios de producción pueden servir su contenido estático desde un nombre de dominio separado para evitar la sobrecarga de transmitir la cookie de sesión para cada solicitud .

Subsitios con prefijos URL comunes para flujos de trabajo, servicio de archivos o particionamiento de sitios. Véase la referencia ^{[ 20 ] [ 21 ].}

Subsitios integrados: Estático, ^{[ 22 ] [ 23 ]} Autenticación ^{[ 24 ]}

Véase la referencia ^{[ 25 ] .}

El tipo de formulario aquí es un objeto que se usa en el controlador para analizar y procesar los campos del formulario ingresados ​​por el usuario y generar un par (FormResult, Widget), donde el widget contiene el diseño de la siguiente representación del formulario con mensajes de error y marcas. También se puede usar para generar un nuevo formulario con campos en blanco o valores predeterminados.

El tipo de formulario adopta la forma de una función de un fragmento HTML que se incrustará en la vista y que contendrá campos ocultos por motivos de seguridad.

Se genera un objeto de formulario a partir de una composición aplicativa - monádica de campos para un análisis secuencial combinado de las entradas de campo.

Existen tres tipos de formularios:

• Aplicativo (con formato tabular),
• Monádico (con estilo de diseño libre), ambos en el módulo Yesod.Form.Functions,
• Entrada (solo para análisis, no se genera ninguna vista) en el módulo Yesod.Form.Input.

Los generadores de campos, cuyos nombres se componen del tipo de formulario inicial (a|m|i)seguido de(req|opt){- required or optional -} , tienen un componente fieldParse y otro fieldView. ^{[ 26 ]}

• La función runForm{Post|Get}analiza los campos del formulario y genera un par (FormResult, Widget) a partir de las vistas, ofreciendo un nuevo widget con los valores de los campos recibidos como valores predeterminados. El sufijo de la función es el método HTTP utilizado para el envío del formulario.
• mientras generateForm{Post|Get}ignora las entradas del cliente y genera un widget de formulario en blanco o con valores predeterminados. ^{[ 27 ]}

Los parámetros y tipos de función reales han cambiado a lo largo de las versiones de Yesod. Consulte las firmas del libro y las bibliotecas de Yesod.

La magia está en la instancia Applicative del tipo de datos FormResult , donde (<*>) recopila los mensajes de error para el caso de valores de resultado ^{[ 28 ].}FormFailure [textErrMsg]

Las formas monádicas permiten un diseño de forma libre y un mejor tratamiento de los miembros hiddenField . ^{[ 25 ]}

Ejemplo de una forma aplicativa ^{[ 29 ] :}

-- un registro para los datos de los campos de nuestro formulario Persona = Persona { personName :: Text , personAge :: Int , personLikings :: Maybe Text }-- El tipo Form tiene un parámetro adicional para insertar un fragmento HTML, que contiene un campo oculto de token CSRF para el tipo de seguridad Form sub master x = Html → MForm sub master ( FormResult x , Widget ){- -- para mensajes en funciones de validación:  @param master: instancia de yesod para usar en renderMessage (devuelto por getYesod del manejador)  @param languages: idiomas de página para usar en renderMessage-- registro de valores predeterminados opcional:  @param mbPersonDefaults: Solo defaults_record, o Nothing para un formulario en blanco -}personForm :: MyFoundationType → [ Texto ] → Quizás Persona → Formulario sub maestro Persona {- ''aopt'' (componente AForm de campo opcional) para campos "Quizás",  ''areq'' (componente AForm de campo obligatorio) insertará el atributo "obligatorio" -} personForm maestro idiomas mbPersonDefaults = renderTable $ Persona <$> areq textField fldSettingsName mbNameDefault <*> areq customPersonAgeField fldSettingsAge mbAgeDefault <*> aopt textareaField fldSettingsLikings mbLikingsDefault donde mbNameDefault = fmap personName mbPersonDefaults mbAgeDefault = fmap personAge mbPersonDefaults mbLikingsDefault = fmap personLikings mbPersonDefaults-- "fieldSettingsLabel" devuelve un registro fieldSettings inicial -- recientemente el registro "FieldSettings" se puede definir a partir de una etiqueta String ya que implementa IsString fldSettingsName = ( fieldSettingsLabel MsgName ) { fsAttrs = [( "maxlength" , "20" )]} fldSettingsAge = fieldSettingsLabel MsgAge fldSettingsLikings = ( fieldSettingsLabel MsgLikings ) { fsAttrs = [( "cols" , "40" ),( "rows" , "10" )]}customPersonAgeField = comprobar validateAge intFieldvalidarEdad y | y < 18 = Izquierda $ renderMessage master languages ​​MsgUnderAge | de lo contrario = Derecha y

• El cuasiconscriptor hamlet (un analizador para código Template Haskell en tiempo de compilación ) ^{[ 2 ] [ 39 ]} especificado en la sintaxis de corchetes TH Oxford introduce una plantilla HTML estructurada basada en indentación. (Véase el documento ^{[ 40 ]} ). ^{[ 41 ]}[qq| ... |]

El símbolo '$' antepone a las líneas de sentencias lógicas.

Las etiquetas de cierre automático se generan únicamente para la etiqueta situada en la posición de inicio de la línea.

• El cuasicitador whamlet devuelve una expresión Widget. (se guarda en Widget antes de [hamlet|..|]).

toWidget [hamlet| $ doctype 5 < html > <!-- solo la etiqueta al principio de la línea se cerrará automáticamente --> <!-- Los prefijos '.' o ' # ' en las etiquetas introducen nombres de clase/id, al estilo CSS --> <!-- El prefijo ":boolVar:" en los atributos los hace generados condicionalmente --> <!-- la interpolación de expresiones haskell sigue la  sintaxis de "plantillas shakespearianas" introducida en la sección así denominada --><head> <title> # { pageTitle } - Mi sitio < link rel = " stylesheet" href = " @ { Stylesheet_route }" > <body> <header> ^ { headerTemplate } < section # mySectionId > <p> < span .titleClass > _ { MsgArticleListTitle } </span> $ if null articles < p : isRed : style = " color : red" > _ { MsgSorryNoArticles } $ else <ul> $ forall art < - articles <li> # { articleNumber art } .- #{ articleTitle art } <footer> ^ { footerTemplate } |] 

Véase la referencia ^{[ 55 ] .}

Los mensajes de la aplicación Yesod son localizables ( i18n ). Deben guardarse en la carpeta de mensajes , en archivos con nombres basados ​​en la ISO , como <idioma-iso> .msg .

Las entradas de mensajes siguen el patrón EBNF :

-- EBNF: identificador, {' ', parámetro, '@', tipo}, ":", texto con interpolaciones ArticleUnexistent param @ Int64 : artículo inexistente # { param }

• Los constructores de mensajes se forman anteponiendo "Msg" al identificador de la etiqueta del mensaje.
• El tipo de datos de mensaje se forma añadiendo "Mensaje" al nombre del tipo base.

-- en el código myMsg :: MyAppMessage -- tipo de datos que agrega "Message" al tipo base myMsg = MsgArticleUnexistent myArticleId -- constructor que antepone "Msg" a msg. label-- en plantillas de widgets _ { MsgArticleUnexistent myArticleId }

Falta la compatibilidad real con i18n en la plantilla de la aplicación Stack . Debe agregarse al archivo "Foundation.hs" para que se muestren los mensajes. ^{[ 56 ]}mkMessage "MyApp" messagesFolder isoLangDefault

• Rutas de navegación . ^{[ 57 ]} Se debe proporcionar una instancia de YesodBreadcrumbs para el sitio donde la función generadora breadcrumb debe devolver para cada ruta un título y uno padre. Luego, la función de consulta breadcrumbs devolverá el título de la ruta actual y los pares (ruta, título) de sus ancestros.

• Mapas del sitio XML de los motores de búsqueda , ^{[ 58 ]} donde sitemap devuelve un mapa del sitio XML como respuesta http , con las rutas que queremos que los motores de búsqueda rastreen y atributos para instruir al rastreador, a partir de una lista proporcionada de registros SitemapUrl .

• Vistas de fuentes web ( RDF Site Summary (RSS) – Atom ). ^{[ 59 ]} Los manejadores devuelven contenido RepRss, RepAtom o RepAtomRss dual (que se seleccionará en la lista de tipos de contenido preferidos de los encabezados de aceptación ) de una estructura de fuente dada .

Por ejemplo, un recuento de visitantes. Véase la referencia ^{[ 60 ] .}

• persistente es el nombre de la capa de acceso a la base de datos con plantillas para generar tipos para entidades y claves, así como la inicialización del esquema. ^{[ 61 ] [ 62 ] [ 63 ]}

Existe soporte de primera clase para PostgreSQL , SQLite , MongoDB , CouchDB y MySQL , con soporte experimental para Redis . ^{[ 61 ]}

El diseño de la base de datos se describe en una plantilla que enumera las entidades, los campos y las restricciones. ^{[ 64 ]}

• Para cada entidad listada, se genera una columna de clave entera "id" con atributos de autoincremento e índice primario, con un alias de tipo que agrega "Id" al nombre de la entidad.
• Para cada entidad listada, se genera un tipo de registro con el mismo nombre que la entidad, donde los nombres de los campos se componen anteponiendo el nombre de la entidad al nombre del campo, como por ejemplo "personName". También se genera un tipo de campo de entidad "PersonName" para referenciar claves foráneas desde otras entidades.
• Existe un mecanismo automático de migración de esquemas de base de datos para las actualizaciones de esquemas de base de datos, que, para tener éxito, requiere, al agregar columnas a tablas existentes, especificar restricciones de valor de columna predeterminado con notación de nivel SQL . ^{[ 65 ]}
• La cardinalidad "como máximo uno" tiene un mecanismo especial en torno al tipo Checkmark. ^{[ 66 ]}
• Las entidades débiles (hijos en relaciones propietario-hijo con restricción de vida) no tienen soporte especial para los disparadores de eliminación en cascada , pero hay funciones para eliminar en cascada manualmente en el módulo Database.Persist.Class. ^{[ 67 ]}

Creación automática de tablas, actualización de esquemas y migración de tablas.

Las modificaciones de la plantilla de entidades producen una actualización del esquema con creación automática de tablas y migración para los sistemas de gestión de bases de datos (DBMS ) que admiten comandos SQL "ALTER TABLE" en un procedimiento migrateAll , generado a partir del contenido de la plantilla. Consulte "Migraciones" en la referencia ^{[ 61 ]} para buscar sistemas de gestión de bases de datos compatibles con migraciones .

compartir [ mkPersist sqlSettings , mkMigrate "migrateAll" -- genera el procedimiento de migración con el nombre especificado ] [ persistir |Usuario -- nombre de tabla y tipo de registro de entidad -- columna de autoincremento implícito "id" como clave primaria, tipo UserId ident Texto -- se refiere a la columna de la tabla de la base de datos "ident"; -- genera un campo de registro que antepone el nombre de la tabla como "userIdent" contraseña Texto Quizás -- Quizás indica campo anulable UniqueUser ident -- restricción única con secuencia de campos separados por espaciosCorreo electrónico : nombre de la tabla y tipo de registro de entidad ; columna de autoincremento implícito "id" como clave primaria, tipo EmailId email Texto usuario UserId ; clave externa especificando otras tablas EntityField tipos verkey Texto QuizásTexto de columna recién agregada "predeterminado='algún texto'::character varying" -- Nivel SQL Restricción predeterminadaUniqueEmail correo electrónico -- restricción única | ]

• Esqueleto: es una capa de combinadores de Haskell para generar consultas relacionales correctas para persistir . ^{[ 68 ]}

Ejemplo de consultas rawSQL persistentes y de Esqueleto . ^{[ 69 ]}