models

package module
v0.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 20, 2024 License: BSD-3-Clause Imports: 5 Imported by: 2

README

License Latest release

models

This is a Go package used to describe data models aligned with the HTML5 data types. The model can be expressed in YAML or JSON. The YAML (or JSON) data structure is patterned after the HTML5 form elements. A single model can be used to generate HTML web forms or used to validate a map that confirms to the model. In princple generators can be written to express the model in other forms, e.g. SQL.

It is important to note that is not an Object Relational Mapper (ORM). The purpose of the model package is to facilitate describing simple data models using YAML then beable to reuse the models in other Go based projects (e.g. dataset, Newt).

This Go package assumes Go version 1.23.1 or better.

Oberservation: Web forms describe a simple data structure

The models package grew out of an observation that if you can define the elements of an HTML5 web form you can also describe a simple data model or schema. The problem is HTML5 is combersum to type, read and work with. On the other hand it lends itself to expression in simpler representations.

YAML can be used to represent a web form in a clear and concise way. From that description you can extrapulate HTML and SQL Schema. You can also use it as a guide to data validation for web form submissions.

Our common use cases.

  1. Web form as YAML can be used to generate HTML web forms
  2. Web form elements can be used to inferring the SQL column type
  3. Web form as YAML is a guide to validating web form submissions

A simple example

A "guest book" model.

id: guest_book_entry
attributes:
  action: ./signbook.html
  method: POST
  x-success: ./thankyou.html
  x-failure: ./oops.html
elements:
  - id: record_id
    type: text
    pattern: [a-z0-9]+\.[a-z0-9]+
    attributes:
      name: record_id
      placeholder: A unique record id
      required: true
  - id: name
    type: text
    attributes:
      name: name
      placeholder: E.g. Doe, Jane
      required: true
  - id: message
    type: text
    attributes:
      placeholder: Please leave a message
      name: message
  - id: signed
    type: date
    attributes:
      name: signed
      required: true

This "model" describes JSON data that might look like the following.

{ 
    "record_id": "jane.doe",
    "Doe, Jane",
    "signed": "2024-09-10"
}

The model could be used to generate the web form and validate the data. It implies an SQL Scheme. The model package provides the means of working with a model and to validate the model's content. By normalizing your data elements to throse supported by HTML5 you also can easily generate the code you need (e.g. HTML form or SQL scheme).

The package doesn't provide the extrapolated forms but does provide the functions and method to make it easy to build them.

Documentation

Index

Constants

View Source
const (
	// Version number of release
	Version = "0.0.1"

	// ReleaseDate, the date version.go was generated
	ReleaseDate = "2024-09-20"

	// ReleaseHash, the Git hash when version.go was generated
	ReleaseHash = "17df42c"

	LicenseText = `` /* 1524-byte string literal not displayed */

)

Variables

This section is empty.

Functions

func ElementToHTML

func ElementToHTML(out io.Writer, cssBaseClass string, elem *Element) error

func FmtHelp

func FmtHelp(src string, appName string, version string, releaseDate string, releaseHash string) string

FmtHelp lets you process a text block with simple curly brace markup.

func ModelToHTML

func ModelToHTML(out io.Writer, model *Model) error

func ModelToSQLiteScheme

func ModelToSQLiteScheme(out io.Writer, model *Model) error

Types

type Element

type Element struct {
	// Type, The type of element that you want to input. It is required. Valid values are
	// checkboxes, dropdown, input, markdown and text area.
	//
	// The input type corresponds to the native input types defined for HTML 5. E.g. text, textarea,
	// email, phone, date, url, checkbox, radio, button, submit, cancel, select
	// See MDN developer docs for input, <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input>
	Type string `json:"type,required" yaml:"type,omitempty"`

	// Id for the element, except when type is set to markdown. Can only use alpha-numeric characters,
	//  -, and _. Must be unique in the form definition. If provided, the id is the canonical identifier
	//  for the field in URL query parameter prefills.
	Id string `json:"id,omitempty" yaml:"id,omitempty"`

	// Attributes, a set of key-value pairs that define the properties of the element.
	// This is a required element as it holds the "value" attribute when expressing
	// HTML content. Other commonly use attributes
	Attributes map[string]string `json:"attributes,omitempty" yaml:"attributes,omitempty"`

	// Pattern holds a validation pattern. When combined with an input type (or input type alias, e.g. orcid)
	// produces a form element that sports a specific client side validation exceptation.  This intern can be used
	// to generate appropriate validation code server side.
	Pattern string `json:"pattern,omitempty" yaml:"pattern,omitempty"`

	// Options holds a list of values and their labels used for HTML select elements in rendering their option child elements
	Options []map[string]string `json:"optoins,omitempty" yaml:"options,omitempty"`

	// IsObjectId (i.e. is the identifier of the object) used by for the modeled data.
	// It is used in calculating routes and templates where the object identifier is required.
	IsObjectId bool `json:"is_primary_id,omitempty" yaml:"is_primary_id,omitempty"`

	// Label is used when rendering an HTML form as a label element tied to the input element via the set attribute and
	// the element's id.
	Label string `json:"label,omitempty" yaml:"label,omitempty"`
	// contains filtered or unexported fields
}

Element implementes the GitHub YAML issue template syntax for an input element. The input element YAML is described at <https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema>

While the syntax most closely express how to setup an HTML representation it is equally suitable to expressing, through inference, SQL column type definitions. E.g. a bare `input` type is a `varchar`, a `textarea` is a `text` column type, an `input[type=date]` is a date column type.

func NewElement

func NewElement(elementId string) (*Element, error)

NewElement, makes sure element id is valid, populates an element as a basic input type. The new element has the attribute "name" and label set to default values.

func (*Element) Check

func (e *Element) Check(buf io.Writer) bool

Check reviews an Element to make sure if is value.

type Model

type Model struct {
	// Id is a required field for model, it maps to the HTML element id and name
	Id string `json:"id,required" yaml:"id"`

	// This is a Newt specifc set of attributes to place in the form element of HTML. I.e. it could
	// be form "class", "method", "action", "encoding". It is not defined in the GitHub YAML issue template syntax
	// (optional)
	Attributes map[string]string `json:"attributes,omitempty" yaml:"attributes,omitempty"`

	// Description, A description for the issue form template, which appears in the template chooser interface.
	// (required)
	Description string `json:"description,required" yaml:"description,omitempty"`

	// Elements, Definition of the input types in the form.
	// (required)
	Elements []*Element `json:"elements,required" yaml:"elements,omitempty"`

	// Title, A default title that will be pre-populated in the issue submission form.
	// (optional)
	Title string `json:"title,omitempty" yaml:"title,omitempty"`
	// contains filtered or unexported fields
}

Model implements a data structure description inspired by GitHub YAML issue template syntax. See <https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms>

The Model structure describes the HTML elements used to form a record. It can be used in code generation and in validating POST and PUT requests in datasetd.

func NewModel

func NewModel(modelId string) (*Model, error)

NewModel, makes sure model id is valid, populates a Model with the identifier element providing returns a *Model and error value.

func (*Model) Check

func (model *Model) Check(buf io.Writer) bool

Check analyze the model and make sure at least one element exists and the model has a single identifier (e.g. "identifier")

func (*Model) GetAttributeIds

func (m *Model) GetAttributeIds() []string

GetAttributeIds returns a slice of attribute ids found in the model's .Elements

func (*Model) GetElementById

func (m *Model) GetElementById(id string) (*Element, bool)

GetElementById returns a Element from the model's .Elements.

func (*Model) GetElementIds

func (m *Model) GetElementIds() []string

GetElementIds returns a slice of element ids found in the model's .Elements

func (*Model) GetModelIdentifier

func (m *Model) GetModelIdentifier() (*Element, bool)

GetModelIdentifier() returns the element which describes the model identifier. Returns the element and a boolean set to true if found.

func (*Model) HasChanges

func (model *Model) HasChanges() bool

HasChanges checks if the model's elements have changed

func (*Model) HasElement

func (model *Model) HasElement(elementId string) bool

HasElement checks if the model has a given element id

func (*Model) HasElementType

func (model *Model) HasElementType(elementType string) bool

HasElementType checks if an element type matches given type.

func (*Model) InsertElement

func (model *Model) InsertElement(pos int, element *Element) error

InsertElement will add a new element to model.Elements in the position indicated, It will also set isChanged to true on additional.

func (*Model) Register

func (model *Model) Register(name string, fn RenderFunc)

Register takes a name (string) and a RenderFunc and registers it with the model. Registered names then can be invoke by the register name.

func (*Model) RemoveElement

func (model *Model) RemoveElement(elementId string) error

RemoveElement removes an element by id from the model.Elements

func (*Model) Render

func (model *Model) Render(out io.Writer, name string) error

Render takes a register render io.Writer and register name envoking the function with the model.

func (*Model) ToHTML

func (model *Model) ToHTML(out io.Writer) error

ToHTML takes a model and trys to render an HTML web form

func (*Model) ToSQLiteScheme

func (model *Model) ToSQLiteScheme(out io.Writer) error

ToSQLiteScheme takes a model and trys to render a SQLite3 SQL create statement.

func (*Model) UpdateElement

func (model *Model) UpdateElement(elementId string, element *Element) error

UpdateElement will update an existing element with element id will the new element.

type RenderFunc

type RenderFunc func(io.Writer, *Model) error

RenderFunc is a function thation takes an io.Writer and Model then renders the model into the io.Writer. It is used to extend the Model to support various output formats.

Directories

Path Synopsis
cmd
modelgen command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL