Skip to content

Commit 8ffc9c5

Browse files
authored
chore(docs): added TextView section (#24)
1 parent 259a657 commit 8ffc9c5

File tree

1 file changed

+70
-10
lines changed

1 file changed

+70
-10
lines changed

README.md

Lines changed: 70 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -40,11 +40,12 @@ go get github.com/yaitoo/xun@latest
4040
`Xun` has some specified directories that is used to organize code, routing and static assets.
4141
- `public`: Static assets to be served.
4242
- `components` A partial view that is shared between layouts/pages/views.
43-
- `views`: A internal page view. It is used in `context.View` to render different view from current routing.
43+
- `views`: An internal page view that can be referenced in `context.View` to render different UI for current routing.
4444
- `layouts`: A layout is shared between multiple pages/views
45-
- `pages`: A public page view. It also is used to automatically create a accessible page routing.
45+
- `pages`: A public page view that will create public page routing automatically.
46+
- `text`: An internal text view that can be referenced in `context.View` to render with a data model.
4647

47-
*NB: All html files(component,layout, view and page) will be parsed by [html/template](https://pkg.go.dev/html/template). You can feel free to use all built-in [Actions,Pipelines and Functions](https://pkg.go.dev/text/template), and your custom functions that is registered in `HtmlViewEngine`.*
48+
**NOTE: All html files(component,layout, view and page) will be parsed by [html/template](https://pkg.go.dev/html/template). You can feel free to use all built-in [Actions,Pipelines and Functions](https://pkg.go.dev/text/template), and your custom functions that is registered in `HtmlViewEngine`.**
4849

4950
### Layouts and Pages
5051
`Xun` uses file-system based routing, meaning you can use folders and files to define routes. This section will guide you through how to create layouts and pages, and link between them.
@@ -110,7 +111,7 @@ You can create a layout(.html) file inside the `layouts` directory.
110111
### Static assets
111112
You can store static files, like images, fonts, js and css, under a directory called `public` in the root directory. Files inside public can then be referenced by your code starting from the base URL (/).
112113

113-
*NB: `public/index.html` will be exposed by `/` instead of `/index.html`.*
114+
**NOTE: `public/index.html` will be exposed by `/` instead of `/index.html`.**
114115

115116
#### Creating a component
116117
A component is a partial view that is shared between multiple layouts/pages/views.
@@ -148,6 +149,66 @@ A component is a partial view that is shared between multiple layouts/pages/view
148149
</html>
149150
```
150151

152+
### Text View
153+
A text view is UI that is referenced in `context.View` to render the view with a data model.
154+
155+
**NOTE: Text files are parsed using the `text/template` package. This is different from the `html/template` package used in `pages/layouts/views/components`. While `text/template` is designed for generating textual output based on data, it does not automatically secure HTML output against certain attacks. Therefore, please ensure your output is safe to prevent code injection.**
156+
157+
#### Creating a text view
158+
```
159+
└── app
160+
├── components
161+
│   └── assets.html
162+
├── layouts
163+
│   └── home.html
164+
├── pages
165+
│   └── index.html
166+
└── public
167+
│ ├── app.js
168+
│ └── skin.css
169+
└── text
170+
├── sitemap.xml
171+
```
172+
173+
#### Render the view with a data model
174+
```go
175+
app.Get("/sitemap.xml", func(c *xun.Context) error {
176+
return c.View(Sitemap{
177+
LastMod: time.Now(),
178+
}, "text/sitemap.xml") // use `text/sitemap.xml` as current Viewer to render
179+
})
180+
```
181+
182+
> curl --header "Accept: application/xml, text/xml,text/plain, */*" -v http://127.0.0.1/sitemap.xml
183+
184+
```bash
185+
* Trying 127.0.0.1:80...
186+
* Connected to 127.0.0.1 (127.0.0.1) port 80
187+
> GET /sitemap.xml HTTP/1.1
188+
> Host: 127.0.0.1
189+
> User-Agent: curl/8.7.1
190+
> Accept: application/xml, text/xml,text/plain, */*
191+
>
192+
* Request completely sent off
193+
< HTTP/1.1 200 OK
194+
< Date: Wed, 15 Jan 2025 11:51:56 GMT
195+
< Content-Length: 277
196+
< Content-Type: text/xml; charset=utf-8
197+
<
198+
<?xml version="1.0" encoding="UTF-8"?>
199+
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
200+
<url>
201+
<loc>https://github.com/yaitoo/xun</loc>
202+
<lastmod>2025-01-15T19:51:56+08:00</lastmod>
203+
<changefreq>hourly</changefreq>
204+
<priority>1.0</priority>
205+
</url>
206+
* Connection #0 to host 127.0.0.1 left intact
207+
</urlset>%
208+
```
209+
210+
211+
151212
## Building your application
152213
### Routing
153214
#### Route Handler
@@ -171,7 +232,7 @@ Page Router only serve static content from html files. We have to define router
171232
```
172233

173234

174-
*NB: An `/index.html` always be registered as `/{$}` in routing table. See more detail on [Routing Enhancements for Go 1.22](https://go.dev/blog/routing-enhancements).*
235+
**NOTE: An `/index.html` always be registered as `/{$}` in routing table. See more detail on [Routing Enhancements for Go 1.22](https://go.dev/blog/routing-enhancements).**
175236
> There is one last bit of syntax. As we showed above, patterns ending in a slash, like /posts/, match all paths beginning with that string. To match only the path with the trailing slash, you can write /posts/{$}. That will match /posts/ but not /posts or /posts/234.
176237
177238
#### Dynamic Routes
@@ -217,11 +278,11 @@ For examples, below patterns will be generated automatically, and registered in
217278
```
218279

219280

220-
### Multiple Viewers based on MIME request
221-
In our application, a routing can have multiple viewers. Response is render based on the request header `Accept`. Default viewer is used if there is no any viewer is matched by `Accept`. The built-it default viewer is `JsonViewer`. But it can be overridden by `xun.WithViewer` in `xun.New`. see more examples on [Tests](app_test.go)
281+
### Multiple Viewers
282+
In our application, a route can support multiple viewers. The response is rendered based on the `Accept` request header. If no viewer matches the `Accept` header, the default viewer is used. The built-in default viewer is `JsonViewer`, but this can be overridden using `xun.WithViewer` when initializing with `xun.New`. For more examples, see the [Tests](app_test.go).
222283

223-
> curl -v http://127.0.0.1
224-
```
284+
```bash
285+
curl -v http://127.0.0.1
225286
> GET / HTTP/1.1
226287
> Host: 127.0.0.1
227288
> User-Agent: curl/8.7.1
@@ -265,7 +326,6 @@ In our application, a routing can have multiple viewers. Response is render base
265326
</body>
266327
</html>
267328
```
268-
269329
### Middleware
270330
Middleware allows you to run code before a request is completed. Then, based on the incoming request, you can modify the response by rewriting, redirecting, modifying the request or response headers, or responding directly.
271331

0 commit comments

Comments
 (0)