diff --git a/htmgo-site/md/docs/1_quick-start/1_introduction.md b/htmgo-site/md/docs/1_quick-start/1_introduction.md index a1b0025..992cdd9 100644 --- a/htmgo-site/md/docs/1_quick-start/1_introduction.md +++ b/htmgo-site/md/docs/1_quick-start/1_introduction.md @@ -1,4 +1,4 @@ -## **Introduction** +## Introduction htmgo is a lightweight pure go way to build interactive websites / web applications using go & htmx. We give you the utilities to build html using pure go code in a reusable way (go functions are components) while also providing htmx functions to add interactivity to your app. diff --git a/htmgo-site/md/docs/1_quick-start/2_installation.md b/htmgo-site/md/docs/1_quick-start/2_installation.md index a12f523..30b1a3e 100644 --- a/htmgo-site/md/docs/1_quick-start/2_installation.md +++ b/htmgo-site/md/docs/1_quick-start/2_installation.md @@ -1,4 +1,4 @@ -## **Getting Started** +## Getting Started ##### **Prerequisites:** diff --git a/htmgo-site/md/docs/2_core-concepts/1_pages.md b/htmgo-site/md/docs/2_core-concepts/1_pages.md index 78140c1..20c0338 100644 --- a/htmgo-site/md/docs/2_core-concepts/1_pages.md +++ b/htmgo-site/md/docs/2_core-concepts/1_pages.md @@ -1,4 +1,4 @@ -## Pages ## +## Pages Pages are the entry point of an htmgo application. diff --git a/htmgo-site/md/docs/2_core-concepts/2_partials.md b/htmgo-site/md/docs/2_core-concepts/2_partials.md index 51a14ef..9757880 100644 --- a/htmgo-site/md/docs/2_core-concepts/2_partials.md +++ b/htmgo-site/md/docs/2_core-concepts/2_partials.md @@ -1,4 +1,4 @@ -## Partials ## +## Partials Partials are where things get interesting. Partials allow you to start adding interactivity to your website by swapping in content, setting headers, redirecting, etc. diff --git a/htmgo-site/md/docs/2_core-concepts/3_components.md b/htmgo-site/md/docs/2_core-concepts/3_components.md index 01c4d62..9cbf2d2 100644 --- a/htmgo-site/md/docs/2_core-concepts/3_components.md +++ b/htmgo-site/md/docs/2_core-concepts/3_components.md @@ -1,4 +1,4 @@ -**Components** +## Components Components are re-usable bits of logic to render HTML. Similar to how in React components are Javascript functions, in htmgo, components are pure go functions. @@ -26,4 +26,4 @@ If you are familiar with React, then you would likely place this fetch logic ins With **htmgo**, the only way to update content on the page is to use htmx to swap out the content from loading a partial. Therefore you control exactly when this Card component is called, not the framework behind the scenes. -See [#interactivity-swapping](#interactivity-swapping) for more information \ No newline at end of file +See [#interactivity-swapping](#interactivity-swapping) for more information diff --git a/htmgo-site/md/docs/2_core-concepts/4_tags.md b/htmgo-site/md/docs/2_core-concepts/4_tags.md index 92912eb..aaeb8ba 100644 --- a/htmgo-site/md/docs/2_core-concepts/4_tags.md +++ b/htmgo-site/md/docs/2_core-concepts/4_tags.md @@ -1,4 +1,4 @@ -**HTML Tags** +## HTML Tags htmgo provides many methods to render html tags: diff --git a/htmgo-site/md/docs/2_core-concepts/5_attributes.md b/htmgo-site/md/docs/2_core-concepts/5_attributes.md index 75e0437..a0b4c73 100644 --- a/htmgo-site/md/docs/2_core-concepts/5_attributes.md +++ b/htmgo-site/md/docs/2_core-concepts/5_attributes.md @@ -1,4 +1,4 @@ -**Attributes** +## Attributes Attributes are one of the main ways we can add interactivity to the pages with [htmx](http://htmx.org). If you have not read over the htmx documentation, please do so before continuing. diff --git a/htmgo-site/md/docs/2_core-concepts/6_raw_html.md b/htmgo-site/md/docs/2_core-concepts/6_raw_html.md index 3e3e7d2..055639c 100644 --- a/htmgo-site/md/docs/2_core-concepts/6_raw_html.md +++ b/htmgo-site/md/docs/2_core-concepts/6_raw_html.md @@ -1,4 +1,4 @@ -**Rendering Raw Html** +## Rendering Raw Html In some cases, you may want to render raw HTML instead of using htmgo's functions. This can be done by using the following methods: @@ -19,4 +19,4 @@ h.UnsafeRawScript("alert('Hello World')") Important: Be careful when using these methods, these methods do not escape the HTML content and should **never** be used with user input unless you have sanitized the input. -Sanitizing input can be done using the `html.EscapeString` function or by using https://github.com/microcosm-cc/bluemonday. \ No newline at end of file +Sanitizing input can be done using the `html.EscapeString` function or by using https://github.com/microcosm-cc/bluemonday. diff --git a/htmgo-site/md/docs/3_control/1_If Else.md b/htmgo-site/md/docs/3_control/1_If Else.md index 2e441cc..3477237 100644 --- a/htmgo-site/md/docs/3_control/1_If Else.md +++ b/htmgo-site/md/docs/3_control/1_If Else.md @@ -1,4 +1,4 @@ -**If / Else Statements** +## Conditional Statements If / else statements are useful when you want to conditionally render attributes or elements / components. diff --git a/htmgo-site/md/docs/3_control/2_loops.md b/htmgo-site/md/docs/3_control/2_loops.md index e3ec62a..c42e87c 100644 --- a/htmgo-site/md/docs/3_control/2_loops.md +++ b/htmgo-site/md/docs/3_control/2_loops.md @@ -1,4 +1,4 @@ -**Loops / Dealing With Lists** +## Loops / Dealing With Lists Very commonly you will need to render a list or slice of items onto the page. Frameworks generally solve this in different ways, such as React uses regular JS .map function to solve it. diff --git a/htmgo-site/md/docs/4_interactivity/1_swapping.md b/htmgo-site/md/docs/4_interactivity/1_swapping.md index 6a9cdc6..d8ba5eb 100644 --- a/htmgo-site/md/docs/4_interactivity/1_swapping.md +++ b/htmgo-site/md/docs/4_interactivity/1_swapping.md @@ -1,4 +1,4 @@ -### Interactivity +## Interactivity / Swapping 1. Adding interactivity to your website is done through [htmx](http://htmx.org) by utilizing various attributes/headers. This should cover most use cases. htmgo offers utility methods to make this process a bit easier @@ -82,4 +82,4 @@ When the **CompleteAll** button is clicked, a **POST** will be sent to the **Com Note: These partial swap methods use https://htmx.org/attributes/hx-swap-oob/ behind the scenes, so it must match the swap target by id. -**If** you are only wanting to swap the element that made the xhr request for the partial in the first place, just use `h.NewPartial` instead, it will use the default htmx swapping, and not hx-swap-oob. \ No newline at end of file +**If** you are only wanting to swap the element that made the xhr request for the partial in the first place, just use `h.NewPartial` instead, it will use the default htmx swapping, and not hx-swap-oob. diff --git a/htmgo-site/md/docs/4_interactivity/2_events.md b/htmgo-site/md/docs/4_interactivity/2_events.md index 40664b5..ed750d8 100644 --- a/htmgo-site/md/docs/4_interactivity/2_events.md +++ b/htmgo-site/md/docs/4_interactivity/2_events.md @@ -1,4 +1,4 @@ -**Events** +## Events Handlers / Commands Sometimes you need to update elements client side without having to do a network call. For this you generally have to target an element with javascript and set an attribute, change the innerHTML, etc. @@ -42,81 +42,4 @@ OnClick(cmd ...Command) *LifeCycle HxOnAfterSwap(cmd ...Command) *LifeCycle HxOnLoad(cmd ...Command) *LifeCycle ``` -**Note:** Each command you attach to the event handler will be passed 'self' and 'event' (if applicable) as arguments. -'self' is the current element, and 'event' is the event object. - -If you use the OnEvent directly, event names may be any [HTML DOM](https://www.w3schools.com/jsref/dom_obj_event.asp) events, or any [HTMX events](https://htmx.org/events/). - -Commands: - -```go -js.AddAttribute(string, value) -js.RemoveAttribute(string) -js.AddClass(string, value) -js.SetText(string) -js.Increment(count) -js.SetInnerHtml(Ren) -js.SetOuterHtml(Ren) -js.SetDisabled(bool) -js.RemoveClass(string) -js.Alert(string) -js.EvalJs(string) // eval arbitrary js, use 'self' to get the current element as a reference -js.InjectScript(string) -js.InjectScriptIfNotExist(string) -js.GetPartial(PartialFunc) -js.GetPartialWithQs(PartialFunc, Qs) -js.PostPartial(PartialFunc) -js.PostPartialWithQs(PartialFunc, Qs) -js.GetWithQs(string, Qs) -js.PostWithQs(string, Qs) -js.ToggleClass(string) -js.ToggleClassOnElement(string, string) - -// The following methods are used to evaluate JS on nearby elements. -// Use 'element' to get the element as a reference for the EvalJs methods. -js.EvalJsOnParent(string) -js.EvalJsOnSibling(string, string) -js.EvalJsOnChildren(string, string) -js.SetClassOnParent(string) -js.RemoveClassOnParent(string) -js.SetClassOnChildren(string, string) -js.RemoveClassOnChildren(string, string) -js.SetClassOnSibling(string, string) -js.RemoveClassOnSibling(string, string) - -``` -For more usages: see https://github.com/maddalax/htmgo/blob/master/htmgo-site/pages/form.go - - -**Example:** Evaluating arbitrary JS - -```go -func MyButton() *h.Element { - return h.Button( - h.Text("Submit"), - h.OnClick( - // make sure you use 'self' instead of 'this' - // for referencing the current element - h.EvalJs(` - if(Math.random() > 0.5) { - self.innerHTML = "Success!"; - } - `, - ), - ), - ) -} -``` - -tip: If you are using Jetbrains IDE's, you can write `// language=js` as a comment above the function call (h.EvalJS) and it will automatically give you syntax highlighting on the raw JS. - -```go -// language=js -h.EvalJs(` - if(Math.random() > 0.5) { - self.innerHTML = "Success!"; - } - `, -), -``` diff --git a/htmgo-site/md/docs/4_interactivity/3_evaluating_javascript.md b/htmgo-site/md/docs/4_interactivity/3_evaluating_javascript.md new file mode 100644 index 0000000..37affdb --- /dev/null +++ b/htmgo-site/md/docs/4_interactivity/3_evaluating_javascript.md @@ -0,0 +1,85 @@ +## Evaluating Javascript In Event Handlers + +Event handlers are useful by attaching **commands** to elements to execute javascript on the client side. + +See [#interactivity-events](#interactivity-events) for more information on event handlers. + +
+ +**Note:** Each command you attach to the event handler will be passed 'self' and 'event' (if applicable) as arguments. +'self' is the current element, and 'event' is the event object. + +If you use the OnEvent directly, event names may be any [HTML DOM](https://www.w3schools.com/jsref/dom_obj_event.asp) events, or any [HTMX events](https://htmx.org/events/). + +Commands: + +```go +js.AddAttribute(string, value) +js.RemoveAttribute(string) +js.AddClass(string, value) +js.SetText(string) +js.Increment(count) +js.SetInnerHtml(Ren) +js.SetOuterHtml(Ren) +js.SetDisabled(bool) +js.RemoveClass(string) +js.Alert(string) +js.EvalJs(string) // eval arbitrary js, use 'self' to get the current element as a reference +js.InjectScript(string) +js.InjectScriptIfNotExist(string) +js.GetPartial(PartialFunc) +js.GetPartialWithQs(PartialFunc, Qs) +js.PostPartial(PartialFunc) +js.PostPartialWithQs(PartialFunc, Qs) +js.GetWithQs(string, Qs) +js.PostWithQs(string, Qs) +js.ToggleClass(string) +js.ToggleClassOnElement(string, string) + +// The following methods are used to evaluate JS on nearby elements. +// Use 'element' to get the element as a reference for the EvalJs methods. +js.EvalJsOnParent(string) +js.EvalJsOnSibling(string, string) +js.EvalJsOnChildren(string, string) +js.SetClassOnParent(string) +js.RemoveClassOnParent(string) +js.SetClassOnChildren(string, string) +js.RemoveClassOnChildren(string, string) +js.SetClassOnSibling(string, string) +js.RemoveClassOnSibling(string, string) + +``` +For more usages: see https://github.com/maddalax/htmgo/blob/master/htmgo-site/pages/form.go + + +**Example:** Evaluating arbitrary JS + +```go +func MyButton() *h.Element { + return h.Button( + h.Text("Submit"), + h.OnClick( + // make sure you use 'self' instead of 'this' + // for referencing the current element + h.EvalJs(` + if(Math.random() > 0.5) { + self.innerHTML = "Success!"; + } + `, + ), + ), + ) +} +``` + +tip: If you are using Jetbrains IDE's, you can write `// language=js` as a comment above the function call (h.EvalJS) and it will automatically give you syntax highlighting on the raw JS. + +```go +// language=js +h.EvalJs(` + if(Math.random() > 0.5) { + self.innerHTML = "Success!"; + } + `, +), +``` diff --git a/htmgo-site/md/docs/5_performance/1_caching_globally.md b/htmgo-site/md/docs/5_performance/1_caching_globally.md index 8ba3258..d8c7e9c 100644 --- a/htmgo-site/md/docs/5_performance/1_caching_globally.md +++ b/htmgo-site/md/docs/5_performance/1_caching_globally.md @@ -1,4 +1,5 @@ -**Caching Components Globally** +## Performance +### Caching Components Globally You may want to cache components to improve performance. This is especially useful for components that are expensive to render or make external requests for data. diff --git a/htmgo-site/md/docs/5_performance/1_caching_per_user.md b/htmgo-site/md/docs/5_performance/1_caching_per_user.md index 5052fef..0857a0a 100644 --- a/htmgo-site/md/docs/5_performance/1_caching_per_user.md +++ b/htmgo-site/md/docs/5_performance/1_caching_per_user.md @@ -1,4 +1,4 @@ -**Caching Components Per User** +## Caching Components Per User If you need to cache a component per user, you can use the `CachedPerKey` functions. These functions allow you to cache a component by a specific key. This key can be any string that uniquely identifies the user. diff --git a/htmgo-site/md/docs/6_pushing_data/1_server_sent_events.md b/htmgo-site/md/docs/6_pushing_data/1_server_sent_events.md index 2e64f89..2a185ab 100644 --- a/htmgo-site/md/docs/6_pushing_data/1_server_sent_events.md +++ b/htmgo-site/md/docs/6_pushing_data/1_server_sent_events.md @@ -1,4 +1,4 @@ -**Server Sent Events (SSE)** +## Server Sent Events (SSE) htmgo supports server-sent events (SSE) out of the box. This allows you to push data from the server to the client in real-time. diff --git a/htmgo-site/md/docs/7_htmx_extensions/1_overview.md b/htmgo-site/md/docs/7_htmx_extensions/1_overview.md index bc3faae..b47de67 100644 --- a/htmgo-site/md/docs/7_htmx_extensions/1_overview.md +++ b/htmgo-site/md/docs/7_htmx_extensions/1_overview.md @@ -1,4 +1,4 @@ -### HTMX Extensions +## HTMX Extensions htmgo provides a few extra htmx extensions to make common tasks easier. Some of these extensions are optional, and some of these are required for htmgo to work correctly. diff --git a/htmgo-site/md/docs/7_htmx_extensions/2_trigger_children.md b/htmgo-site/md/docs/7_htmx_extensions/2_trigger_children.md index 9b67eeb..0caf026 100644 --- a/htmgo-site/md/docs/7_htmx_extensions/2_trigger_children.md +++ b/htmgo-site/md/docs/7_htmx_extensions/2_trigger_children.md @@ -1,4 +1,4 @@ -### HTMX Extensions - Trigger Children +## HTMX Extensions - Trigger Children The `trigger-children` extension allows you to trigger an event on all children and siblings of an element. diff --git a/htmgo-site/md/docs/7_htmx_extensions/3_mutation_error.md b/htmgo-site/md/docs/7_htmx_extensions/3_mutation_error.md index 4cd5e0d..467206a 100644 --- a/htmgo-site/md/docs/7_htmx_extensions/3_mutation_error.md +++ b/htmgo-site/md/docs/7_htmx_extensions/3_mutation_error.md @@ -1,4 +1,4 @@ -### HTMX Extensions - Mutation Error +## HTMX Extensions - Mutation Error The `mutation-error` extension allows you to trigger an event when a request returns a >= 400 status code. diff --git a/htmgo-site/md/docs/8_miscellaneous/1_tailwind_intellisense.md b/htmgo-site/md/docs/8_miscellaneous/1_tailwind_intellisense.md index b494125..8c958dc 100644 --- a/htmgo-site/md/docs/8_miscellaneous/1_tailwind_intellisense.md +++ b/htmgo-site/md/docs/8_miscellaneous/1_tailwind_intellisense.md @@ -1,4 +1,4 @@ -### Tailwind intellisense +## Tailwind intellisense Tailwind's language server allows you to specify custom configuration on what it should match to start giving you tailwind intellisense. diff --git a/htmgo-site/md/docs/8_miscellaneous/2_converting_raw_html_to_go.md b/htmgo-site/md/docs/8_miscellaneous/2_converting_raw_html_to_go.md index 6ac6987..54fb86c 100644 --- a/htmgo-site/md/docs/8_miscellaneous/2_converting_raw_html_to_go.md +++ b/htmgo-site/md/docs/8_miscellaneous/2_converting_raw_html_to_go.md @@ -1,4 +1,4 @@ -### Converting Raw HTML to Go +## Converting Raw HTML to Go In some cases, you may want to convert raw HTML to Go code. A tool to do this automatically is available here: https://htmgo.dev/html-to-go diff --git a/htmgo-site/md/docs/9_troubleshooting/1_common_issues.md b/htmgo-site/md/docs/9_troubleshooting/1_common_issues.md index 3e64a82..e9d9792 100644 --- a/htmgo-site/md/docs/9_troubleshooting/1_common_issues.md +++ b/htmgo-site/md/docs/9_troubleshooting/1_common_issues.md @@ -1,4 +1,4 @@ -## **Troubleshooting:** +## Troubleshooting: **command not found: htmgo** -ensure you installed htmgo above and ensure GOPATH is set in your shell \ No newline at end of file +ensure you installed htmgo above and ensure GOPATH is set in your shell