{"id":13541939,"url":"https://github.com/codelv/enaml-web","last_synced_at":"2025-04-12T22:28:43.612Z","repository":{"id":16755459,"uuid":"80592264","full_name":"codelv/enaml-web","owner":"codelv","description":"Build interactive websites with enaml","archived":false,"fork":false,"pushed_at":"2025-03-19T21:59:29.000Z","size":43527,"stargazers_count":104,"open_issues_count":7,"forks_count":18,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-04-04T01:41:23.166Z","etag":null,"topics":["enaml","lxml","python","web","web-components"],"latest_commit_sha":null,"homepage":"https://codelv.com/projects/enaml-web/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codelv.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-02-01T05:24:35.000Z","updated_at":"2025-03-29T07:32:35.000Z","dependencies_parsed_at":"2024-01-16T15:49:06.439Z","dependency_job_id":"4d236052-404c-4864-a1be-9c897a30fb73","html_url":"https://github.com/codelv/enaml-web","commit_stats":{"total_commits":207,"total_committers":6,"mean_commits":34.5,"dds":"0.32367149758454106","last_synced_commit":"a568c5007ae7db6eefe37232f3f3e62ce21a9e55"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codelv%2Fenaml-web","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codelv%2Fenaml-web/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codelv%2Fenaml-web/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codelv%2Fenaml-web/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codelv","download_url":"https://codeload.github.com/codelv/enaml-web/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248639290,"owners_count":21137818,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["enaml","lxml","python","web","web-components"],"created_at":"2024-08-01T10:00:59.143Z","updated_at":"2025-04-12T22:28:43.593Z","avatar_url":"https://github.com/codelv.png","language":"Python","readme":"# Enaml Web #\n\n[![status](https://github.com/codelv/enaml-web/actions/workflows/ci.yml/badge.svg)](https://github.com/codelv/enaml-web/actions)\n[![codecov](https://codecov.io/gh/codelv/enaml-web/branch/master/graph/badge.svg)](https://codecov.io/gh/codelv/enaml-web)\n[![Downloads](https://pepy.tech/badge/enaml-web/month)](https://pepy.tech/project/enaml-web/)\n\nA web component toolkit for [enaml](https://github.com/nucleic/enaml) that\nlet's you build websites in python declaratively.\n\nYou can use enaml-web to build \"interactive\" websites using python, enaml, and a few lines of _simple_ javascript (see the simple pandas [dataframe viewer](https://github.com/codelv/enaml-web/tree/master/examples/dataframe_viewer) example). The view state (dom) is stored on the server as an enaml view and interaction works by syncing changes between\nbetween the client(s) and server using websockets (or polling).\n\nTo demonstrate, the following interaction is all handled with enaml-web\n\n![interactive-websites-in-python-with-enaml](https://user-images.githubusercontent.com/380158/44675893-b4ceb380-a9ff-11e8-89e9-9ca2bce7d217.gif)\n\n\n### Examples\n\nSee the examples folder\n\n- [www.codelv.com](https://www.codelv.com/) - Built entirely using enaml-web\n- [SMD Component search](https://github.com/frmdstryr/smd-search) - View and search a pandas dataframe\n\nHave a site? Feel free to share it!\n\n### Why?\n\nIt makes it easy to build websites without a lot of javascript.\n\n### Short intro\n\nTo use enaml web, you simply replace html tags with the enaml component\n(the capitalized tag name). For example:\n\n```python\nfrom web.components.api import *\n\nenamldef Index(Html):\n    Head:\n        Title:\n            text = \"Hello world\"\n    Body:\n        H1:\n            text = \"Render a list!\"\n        Ul:\n            Looper:\n                iterable = range(3)\n                Li:\n                    style = 'color: blue' if loop.index \u0026 1 else ''\n                    text = loop.item\n\n```\n\nCalling `render()` on an instance of this enaml view then generates the html\nfrom the view. This is shown in the simple case of a static site generator:\n\n```python\n\nimport enaml\nfrom web.core.app import WebApplication\n\n# Create an enaml Application that supports web components\napp = WebApplication()\n\n# Import Index from index.enaml\nwith enaml.imports():\n    from index import Index\n\n# Render the Index.enaml to index.html\nview = Index()\nwith open('index.html', 'w') as f:\n    f.write(view.render())\n\n```\n\nYou can also use it in a request handler with your favorite web framework. For example with tornado\nweb you can do something like this:\n\n\n```python\nimport enaml\nimport tornado.web\nimport tornado.ioloop\nfrom web.core.app import WebApplication\n\n# Import Index from index.enaml\nwith enaml.imports():\n    from index import Index\n\nclass IndexHandler(tornado.web.RequestHandler):\n    view = Index()\n    def get(self, request):\n        return self.view.render(request=request)\n\nclass Application(tornado.web.Application):\n    def __init__(self):\n        super(Application, self).__init__([\n                (r'/',IndexHandler)\n           ],\n        )\n\nif __name__ == \"__main__\":\n    web_app = WebApplication()\n    app = Application()\n    app.listen(8888)\n    tornado.ioloop.IOLoop.current().start()\n\n```\n\n### So what's the advantage over plain html?\n\nIt's as simple as html but it's python so you can, loop over lists, render conditionally,\nformat variables, etc...\n\nAlso, it's not just formatting a template,  the server maintains the page state so\nyou can interact with the page after it's rendered.  This is something that no other\npython template frameworks can do (to my knowledge).\n\n### How it works\n\nIt simply generates a tree of [lxml](http://lxml.de/) elements.\n\n#### Advantages\n\n1. Inherently secure\n\nSince it's using lxml elements instead of text, your template code is inherently secure from\ninjection as lxml automatically escapes all attributes. A closing tag cannot be accidentally missed.\n\nThe atom framework provides additional security by enforcing runtime type\nchecking and optional validation.\n\n2. Minified by default\n\nOther templates engines often render a lot of useless whitespace. This does not. The response is always minified.\n\n3. No template tags needed\n\nSome template engines require the use of \"template tags\" wrapped in `{% %}`\nor similar to allow the use of python code to transform variables.\n\nSince enaml _is_ python, you can use any python code directly in\nyour enaml components and templates. You don't need any template tags.\n\n4. Templates can be modified\n\nThe tree can be modified after it's rendered to react to events or data changes. These\nchanges can be propogated out to clients (see the data binding section).\n\n5. Component based\n\nSince enaml views are like python classes, you can \"subclass\" and extend any\ncomponent and extend it's functionality. This enables you to quickly build\nreusable components. This is like \"web components\" but it's rendered server side\nso it's not slow. See [materialize-ui](https://github.com/frmdstryr/materialize) for an example.\n\n#### Disadvantages\n\n1. Memory usage\n\nEven though lxml is written in c and enaml uses atom objects, the memory usage may still\nbe more than plain string templates.\n\n2. HTML only\n\nIt only works with html.\n\n\n### Data binding\n\nBecause enaml-web is generating a dom, you can use websockets and some js\nto manipulate the dom to do data binding between the client to server.\n\nThe dom can be shared per user or per session making it easy to create\ncollaborative pages or they can be unique to each page.\n\n![Data binding](https://github.com/frmdstryr/enaml-web/blob/master/docs/data-binding.gif?raw=true)\n\nEach node has a unique identifier and can be modified using change events. An\nexample of this is in the examples folder.\n\nYou can also have the client trigger events on the server and have the server\ntrigger JS events on the client.\n\nTo use:\n1. Include a client side script in your page to process modified events\n2. Observe the `modified` event of an Html node and pass these changes to the\nclient via websockets.\n3. Make a handlers on the server side to update dom accordingly.\n\n\nSee [app.js](examples/dataframe_viewer/app.js#L7) for an example client\nside handler and [app.py](examples/dataframe_viewer/app.py#L70) for an example\nserver side handler.\n\n##### Modified events\n\nThe modified events will be a dict. The keys depend on the event type but the\ngeneral format is:\n\n```python\n{\n  'id': 'id-of-node', # ID of node where the event originated\n  'type': 'update', # Type of event, eg, update, added, removed, etc..\n  'name': 'attr-modified', # Attr name that was modified, eg `cls` or `children`\n  'value': object, # Depends on the event type\n  # May have other events\n}\n```\n\nFor example, changing the `style` attribute on a node will generate an event like\n\n```python\n{\n  'id': 'id-of-a-node',\n  'type': 'update',\n  'name': 'style',\n  'value': 'color: blue',\n  'oldvalue': 'color: red'\n}\n```\n\nInserting a new list item node will generate an event like\n\n```python\n{\n  'id': 'id-of-my-list',\n  'type': 'added',\n  'name': 'children',\n  'value': '\u003cli\u003eNew item\u003c/li\u003e',\n  'before': 'id-of-node-to-insert-before', \n}\n\n```\n\nThe full list of events can be found in the base [Tag](web/components/html.py)\nby searching for `_notify_modified` calls. You can also generate your own\ncustom events as needed.\n\n#### Data models\n\nForms can automatically be generated and populated using enaml's DynamicTemplate\nnodes. An implementation of the `AutoForm` using the [materalize css](https://github.com/frmdstryr/materialize)\nframework is available on my personal repo. With this, we can take a model like:\n\n```python\n\nfrom atom.api import Atom, Unicode, Bool, Enum\n\nclass Message(Atom):\n    name = Unicode()\n    email = Unicode()\n    message = Unicode()\n    options = Enum(\"Email\",\"Phone\",\"Text\")\n    sign_up = Bool(True)\n\n\n```\n\nThen use the `AutoForm` node and pass in either a new or populated instance of\nthe model to render the form.\n\n```python\n\nfrom templates import Base\nfrom web.components.api import *\nfrom web.core.api import Block\n\n\nenamldef AddMessageView(Base): page:\n    attr message\n    Block:\n        block = page.content\n        AutoForm:\n            model \u003c\u003c message\n\n```\n\n### Database ORM with Atom\n\nFor working with a database using atom see [atom-db](https://github.com/codelv/atom-db)\n\n\n#### Raw, Markdown, and Code nodes\n\nThe`Raw` node parses text into dom nodes (using lxml's html parser). Similarly\n`Markdown` and `Code` nodes parse markdown and highlight code respectively.\n\nFor example, you can show content from a database like tihs:\n\n```python\n\nfrom web.components.api import *\nfrom web.core.api import *\nfrom myapp.views.base import Page\n\nenamldef BlogPage(Page):\n    attr page_model: SomeModel # Page model\n    body.cls = 'template-blogpage'\n    Block:\n        block = parent.content\n        Raw:\n            # Render source from database\n            source \u003c\u003c page_model.body\n\n```\n\nThis let's you use web wysiwyg editors to insert content into the dom. If the content\nis not valid it will not mess up the rest of the page.\n\n\n### Block nodes\n\nYou can define a base template, then overwrite parts using the `Block` node.\n\nIn one file put:\n\n```python\n\nfrom web.components.api import *\nfrom web.core.api import Block\n\nenamldef Base(Html):\n    attr user\n    attr site\n    attr request\n    alias content\n    Head:\n        Title:\n            text \u003c\u003c site.title\n    Body:\n        Header:\n            text = \"Header\"\n        Block: content:\n            pass\n        Footer:\n            text = \"Footer\"\n\n```\n\nThen you can import that view and _extend_ the template and override the\nblock's content.\n\n```python\nfrom templates import Base\nfrom web.components.api import *\nfrom web.core.api import Block\n\nenamldef Page(Base): page:\n    Block:\n        block = page.content\n        P:\n            text = \"Content inserted between Header and Footer\"\n\n```\n\nBlocks let you either replace, append, or prepend to the content.\n\n\n### Gotchas\n\n##### Text and tail nodes\n\nLxml uses text and tail properties to set text before and after child nodes, which can be confusing.\n\nFor instance in html you can do\n\n```html\n\n\u003cp\u003eThis is a sentence \u003ca href=\"#\"\u003eclick here\u003c/a\u003e then keep going\u003c/p\u003e\n\n```\n\nTo make this with enaml you need to do this:\n\n```python\n\nP:\n    text = \"This is a sentence\"\n    A:\n        href = \"#\"\n        text = \"click here\"\n        tail = \"then keep going\"\n\n```\n\nNotice how `tail` is set on the `A` NOT the `P`.\nSee [lxml etree documentation](http://lxml.de/tutorial.html#elements-contain-text) for more details.\n\n\n##### Tag attribute\n\nWhen creating a custom `Tag`, the `tag` attribute must be set to change what\nhtml tag is used for a node. For example:\n\n```python\n\nenamldef Svg(Tag):\n    tag = 'svg' # Force tag to be 'svg'\n\n```\n\nThis will then render a `\u003csvg\u003e...\u003c/svg\u003e` tag.\n\n\u003e Note: In previous versions (0.8.8 and below) the tag name defaulted to the\nlowercase class name. This is no longer done to eliminate a function call per\nnode and to avoid having to explicitly redefine the tag when subclassing.\n\n##### Generic attributes\n\nThe [html](https://github.com/codelv/enaml-web/blob/master/web/components/html.py)\ndefinitions only expose the commonly used attributes of each node,\nsuch as `cls`, `style`, and those specific to the tag (such as or `href` for a link).\n\nCustom attributes or attributes which can't be set as a name in python\n(such as `data-tooltip`) can defined by assigning `attrs` to a `dict` of\nattr value pairs.\n\n```python\nenamldef Tooltip(Span):\n    attrs = {'data-tooltip': 'Tooltip text'}\n```\n\nThis will create a node like:\n\n```html\n\u003cspan data-tooltip=\"Tooltip text\"\u003e\u003c/span\u003e\n```\n","funding_links":[],"categories":["HTML Generation","Front-end frameworks"],"sub_categories":["More"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodelv%2Fenaml-web","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodelv%2Fenaml-web","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodelv%2Fenaml-web/lists"}