Drafter Documentation for Students

Basic Routing

@route
@route(url)

Decorator to turn a function into route connected to a URL. If the url is not given, then the function’s name will be used as the route. Unless the name of the function is index, in which case that route will be used as the index of the website (the front, default page).

Parameters:

url (str) – The URL to connect to the function as a route. Defaults to function’s name, if not given.

Pages

Page(state, content)

Constructor function for the Page object, which holds all the information for a viewable web page. The state is hidden from the user, but the content is rendered into HTML. This should be returned from any route function.

The content is a list of either string values or Component instances. The strings can contain actual HTML, which will be injected directly into the page. The Component instances will also be turned into HTML.

Parameters:

  • state – The new value of the page, hidden from the user. This is usually an instance of a dataclass. If there is no change to the state, then will just be the state parameter.

  • content (list[str | Component]) – The actual content of the page, eventually rendered as HTML in the browser. Can combine both string values and Component instances.

Server Control

start_server()
start_server(inital_state)

Function to start the server and launch the website. The local URL of the server will be displayed, usually defaulting to http://localhost:8080/. No code will be executed after this call.

The initial_state should match the type of the first parameter for every route. If no initial_state is given, then the state will initially be None.

Parameters:

initial_state – The initial state of the website, usually a dataclass instance. Defaults to None.

Components

Image(url)
Image(url, width, height)

An image to be displayed on the page. Usually needs to be a complete URL, including the http:// or https://. Note that some websites may not allow you to use their images on your website, so be careful; you may want to rehost the image somewhere more reliable.

If you know the exact size of the image, you can specify it with the width and height parameters. Otherwise, the page may resize while the image is being loaded.

Parameters:

  • url (str) – The URL of the image.

  • width (int) – The width of the image, in pixels. Defaults to None, which will use the image’s default width.

  • height (int) – The height of the image, in pixels. Defaults to None, which will use the image’s default height.

A link to another page. The text is what will be displayed on the page, and the url is where the link will take you. This gets rendered as a normal HTML link (underlined blue text). If you want to use a button instead, use the Button component.

Parameters:

  • text (str) – The text to display for the link.

  • url (str or function) – Either a string representing the full URL you are linking to (possibly external to the server) or the name of a function that is a route on the server (without quotes or calling parentheses).

TextBox(name)
TextBox(name, default_value)

A text box for the user to enter text. The name is the name of the text box, which will be used to identify the text box when the user submits the form (and becomes a parameter to the linked page). The default_value is the initial value of the text box, which will be displayed to the user. If no default_value is provided, the textbox will initially be empty.

Parameters:

  • name (str) – The name of the text box, which will be used to identify the text box when the user submits the form. Make sure this is a valid Python identifier (start with a letter followed only by letters, numerals, and underscores). This must match the same parameter name in the corresponding linked route.

  • default_value (str) – The initial value of the text box, which will be displayed to the user. Defaults to None, which will make the text box initially empty.

TextArea(name)
TextArea(name, default_value)

A multiline text area for the user to enter text. Basically the same as the TextBox component, but with multiple lines. The name is the name of the text area, which will be used to identify the text area when the user submits the form (and becomes a parameter to the linked page). The default_value is the initial value of the text area, which will be displayed to the user. If no default_value is provided, the text area will initially be empty.

Parameters:

  • name (str) – The name of the text area, which will be used to identify the text area when the user submits the form. Make sure this is a valid Python identifier (start with a letter followed only by letters, numerals, and underscores). This must match the same parameter name in the corresponding linked route.

  • default_value (str) – The initial value of the text area, which will be displayed to the user. Defaults to None, which will make the text area initially empty.

SelectBox(name, options)
SelectBox(name, options, default_value)

A dropdown box for the user to select a single option. The name is the name of the dropdown box, which will be used to identify the dropdown box when the user submits the form (and becomes a parameter to the linked page). The options is a list of strings representing the options in the dropdown box. The default_value is the initial value of the dropdown box, which will be displayed to the user. If no default_value is provided, the dropdown box is probably the first element of the list, or the last one, or maybe blank.

These boxes are also sometimes called combo boxes, dropdowns, or select lists.

Parameters:

  • name (str) – The name of the select box, which will be used to identify the select box when the user submits the form. Make sure this is a valid Python identifier (start with a letter followed only by letters, numerals, and underscores). This must match the same parameter name in the corresponding linked route.

  • options (list[str]) – The list of options to display in the select box. Each option should be a string.

  • default_value (str) – The initial value of the select box, which will be displayed to the user. Defaults to None, which will make the select box initially empty.

CheckBox(name)
CheckBox(name, default_value)

A check box for the user to select. The name is the name of the check box, which will be used to identify the check box when the user submits the form (and becomes a parameter to the linked page). The default_value is the initial value of the check box, which will be displayed to the user. If no default_value is provided, the check box will initially be unchecked.

Parameters:

  • name (str) – The name of the check box, which will be used to identify the check box when the user submits the form. Make sure this is a valid Python identifier (start with a letter followed only by letters, numerals, and underscores). This must match the same parameter name in the corresponding linked route.

  • default_value (bool) – The initial value of the check box, which will be displayed to the user. Defaults to None, which will make the check box initially unchecked.

LineBreak()

A line break in the page. This is a single line break, forcing a new line on the page. It is the same as the HTML <br> tag.

HorizontalRule()

A horizontal line stretching across the page. This is the same as the HTML <hr> tag.

Button(text, url)
Button(text, url, arguments)

A clickable button on the page. The text is what will be displayed on the button, and the url is where the button will take you. This gets rendered as a normal HTML button. All of the input fields on the page will be submitted with the button press, and passed as parameters to the linked page.

Parameters:

  • text (str) – The text to display for the button.

  • url (str or function) – Either a string representing the full URL you are linking to (possibly external to the server) or the name of a function that is a route on the server (without quotes or calling parentheses).

  • arguments (list[Argument]) – Any additional arguments to pass to the server when the button is pressed. These should be Argument instances. Defaults to an empty list.

NumberedList(items)

A numeric, ordered list of items. The items is a list of strings, each of which will be a separate item in the list. This gets rendered as a normal HTML ordered list.

Parameters:

items (list[str]) – The list of items to display in the ordered list. Each item should be a string. If they are not strings, then they will be converted using the builtin str function.

BulletedList(items)

An unordered, enumerated list. The items is a list of strings, each of which will be a separate item in the list. This gets rendered as a normal HTML unordered list.

Parameters:

items (list[str]) – The list of items to display in the unordered list. Each item should be a string. If they are not strings, then they will be converted using the builtin str function.

Header(body, level)

A text header of different sizes. The body is the text to display in the header. The level is the size of the header, with 1 being the largest and 6 being the smallest. If no level is given, then it will default to 1.

Parameters:

  • body (str) – The text to display in the header.

  • level (int) – The size of the header, with 1 being the largest and 6 being the smallest. Defaults to 1.

Table(data)

A tabular representation of data. The data is a list of lists, where each inner list is a row in the table. The data can also be a list of dataclass instances, which will be rendered as a pleasant table. If a single dataclass is passed in, that will be rendered with the fields as rows in the table.

Parameters:

data (list[list[str]] or list[object] or object) – The data to display in the table. Each row should be a list of strings, list of dataclass instances, or a single dataclass instance.

Span(...components)

A span of text with multiple components. The components can be any number of strings or Component instances, which will be rendered in the span. This is useful for combining multiple components into a single line.

Parameters:

components (str | Component) – The components to display in the span. Each component should be a string or a Component instance. You do not pass them in as a list, but as separate arguments (like the print) function.

Argument(name, value)

A hidden argument to be passed to the server. The name is the name of the argument, and the value is the value. You can only use strings, integers, floats, or booleans as values. This is useful for passing information to the server without displaying it to the user.

A major use for this feature is as an additional parameter to buttons. If you want to pass additional information to the server when a button is pressed, you can use this component to do so.

Button("Submit", some_route, Argument("additional_info", "extra_data"))

Note that buttons must have unique names, or the arguments will not be distinguishable.

Debug Information

show_debug_information()

Show the debug information at the bottom, including the current route, current state, the list of available routes, and the history of visited pages.

hide_debug_information()

Hide the debug information at the bottom.