diff --git a/.vitepress/config.mts b/.vitepress/config.mts index 1a04231..c050c9d 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -11,46 +11,14 @@ export default defineConfig({ ], sidebar: [ { - text: "Getting Started", + text: "Guide", items: [ { text: "Intro", link: "/guide/" }, - { text: "Setup", link: "/guide/setup" } - ] - }, - { - text: "Rails", - items: [ - { text: "Views", link: "/guide/rails/views" }, - { text: "Generators" }, - { text: "Migrating to Phlex" }, - ], - }, - { - text: "HTML", - collapsed: false, - items: [ - { text: "Introduction" }, - { text: "Elements" }, - { text: "Attributes" }, - { text: "Comments" }, - { text: "Helpers" }, - { text: "Whitespace" }, + { text: "Setup", link: "/guide/setup" }, + { text: "Your first component", link: "/guide/first-component" }, + { text: "Under the hood", link: "/guide/under-the-hood" }, ], }, - { - text: "SVG", - collapsed: false, - items: [ - { text: "Introduction" }, - { text: "Elements" }, - { text: "Attributes" }, - ], - }, - { - text: "CSV", - collapsed: false, - items: [{ text: "Introduction" }, { text: "CSV Injection" }], - }, ], socialLinks: [ @@ -61,4 +29,4 @@ export default defineConfig({ message: "Released under the MIT License.", }, }, -}) +}); diff --git a/guide/first-component.md b/guide/first-component.md new file mode 100644 index 0000000..3384f30 --- /dev/null +++ b/guide/first-component.md @@ -0,0 +1 @@ +# Building your first component in Phlex diff --git a/guide/setup.md b/guide/setup.md index f292a21..eb84b66 100644 --- a/guide/setup.md +++ b/guide/setup.md @@ -1,21 +1,23 @@ -# Setup +# Up and running đââĄď¸ -## Setting up Phlex with Rails +Before we get too far, letâs get Phlex up and running in your app. -Letâs be honest, most of us are going to be using this with Rails so weâll start there. +Phlex is a standalone Ruby library with zero dependencies, but most folks will want to use it with [Ruby on Rails](https://rubyonrails.org) so letâs start there for the sake of this guide. -First, add `phlex-rails` to your Gemfile. The quickest way to do this is to run: +Itâs possible to use Phlex with [Sinatra](https://sinatrarb.com), [Roda](https://github.com/jeremyevans/roda), [Hanami](https://hanamirb.org), and any other Ruby web framework, but youâll need to kick off the rendering yourself. + +## Installing Phlex in a Rails app + +To install Phlex in a Rails app, youâll need to add the `phlex-rails` gem to your `Gemfile`. The `phlex-rails` gem includes the `phlex` gem as a dependency, so you wonât need to add that separately. `phlex-rails` also includes a generator to help you get started. + +Start by running: ``` bundle add phlex-rails ``` -This will add the latest version of `phlex` and `phlex-rails` and run `bundle install` for you. Now that the gem is installed, youâll want to run the install geneartor: +This will install the latest version of `phlex` and `phlex-rails` and add `phlex-rails` to your `Gemfile`. Once thatâs finished, youâll want to run the install geneartor to kick things off: ``` bundle exec rails generate phlex:install ``` - -## Setting up Phlex without Rails - -Phlex is actually a standalone library with zero dependencies. You can use it in any Ruby project, but youâll need to kick off the rendering yourself. diff --git a/guide/under-the-hood.md b/guide/under-the-hood.md new file mode 100644 index 0000000..bbfa9cf --- /dev/null +++ b/guide/under-the-hood.md @@ -0,0 +1,89 @@ +# Under the hood + +Youâve successfully installed Phlex and rendered your first component. Now letâs take a moment to understand whatâs happening behind the scenes. To do this, weâre going to build a mineature version of Phlex from scratch. + +It wonât have advanced features, performance optimizations or HTML safety, but I think itâll give you a good sense of things. + +## Buffers and hirearchy + +Weâll start by creating a `Component` class with a `@buffer` instance variable. Phlex uses a mutible String for its buffer, but weâll use an Array since itâs easier to debug. + +```ruby +class Component + def initialize + @buffer = [] + end +end +``` + +Now we want to be able to render HTML tags. Letâs start with `