From 160d18e40b6ac02d95b9a73e17b5bd9bdc9a2d6e Mon Sep 17 00:00:00 2001 From: Mattes Mohr Date: Sat, 26 Nov 2022 16:46:00 +0100 Subject: [PATCH] Update the documentation (#105) * Rearrange the documentation files * Update the main article * Add an article to explain the vapor integration * Update the getting started article * Update the conversion article * Update the globalization article * Add an article with an element overview * Update some articles * Add articles for the components * Update the articles of the components * Update the abstraction article * Add an article to explain the css deployment * Rename some files * Update some of the articles * Update the readme file * Update some of the articles --- README.md | 4 +- .../Core/Primitives/Layouts/Layouts.swift | 6 - .../HTMLKit.docc/Essentials/GettingStarted.md | 31 +++ .../Essentials/Getting_started.md | 42 ---- .../HTMLKit.docc/Essentials/Parts/Elements.md | 75 -------- .../HTMLKit.docc/Essentials/Parts/Layouts.md | 59 ------ .../Essentials/Parts/Statements.md | 45 ----- .../Essentials/VaporIntegration.md | 45 +++++ .../HTMLKit.docc/Features/Conversion.md | 48 ----- .../HTMLKit.docc/Features/Localization.md | 59 ------ .../HTMLKit.docc/Features/Templating.md | 55 ------ .../HTMLKit.docc/Framework/Components.md | 74 +++++++ .../Framework/Components/ActionButton.md | 27 +++ .../Framework/Components/CheckField.md | 21 ++ .../Framework/Components/Collection.md | 23 +++ .../Framework/Components/DatePicker.md | 21 ++ .../Framework/Components/Divider.md | 15 ++ .../Framework/Components/FieldLabel.md | 17 ++ .../HTMLKit.docc/Framework/Components/Form.md | 20 ++ .../Framework/Components/HStack.md | 29 +++ .../Framework/Components/Image.md | 29 +++ .../HTMLKit.docc/Framework/Components/Link.md | 37 ++++ .../HTMLKit.docc/Framework/Components/List.md | 25 +++ .../Framework/Components/ProgressView.md | 16 ++ .../Framework/Components/RadioSelect.md | 21 ++ .../Framework/Components/ResetButton.md | 27 +++ .../Framework/Components/SearchField.md | 21 ++ .../Framework/Components/SecureField.md | 21 ++ .../Framework/Components/SelectField.md | 22 +++ .../Framework/Components/Slider.md | 15 ++ .../Framework/Components/Snippet.md | 19 ++ .../Framework/Components/SubmitButton.md | 27 +++ .../HTMLKit.docc/Framework/Components/Text.md | 37 ++++ .../Framework/Components/TextEditor.md | 25 +++ .../Framework/Components/TextField.md | 21 ++ .../Framework/Components/Toggle.md | 15 ++ .../Framework/Components/VStack.md | 29 +++ .../Framework/Components/ZStack.md | 24 +++ .../HTMLKit.docc/Framework/Elements.md | 182 ++++++++++++++++++ .../HTMLKit.docc/Framework/Globalization.md | 43 +++++ .../Framework/Globalization/Localization.md | 34 ++++ .../HTMLKit.docc/Framework/Statements.md | 29 +++ .../Framework/Statements/Foreach.md | 16 ++ .../Framework/Statements/Ifelse.md | 5 + .../Framework/Statements/Unwrap.md | 13 ++ .../HTMLKit.docc/Framework/Template.md | 34 ++++ .../Template/Annotations/TemplateValue.md | 5 + .../Parts => Framework/Template}/Context.md | 10 + .../Framework/Template/Layouts.md | 51 +++++ .../Framework/Template/Layouts/Page.md | 25 +++ .../Framework/Template/Layouts/View.md | 18 ++ Sources/HTMLKit/HTMLKit.docc/HTMLKit.md | 43 +++-- .../HTMLKit.docc/Plugins/ComponentsPlugin.md | 15 ++ .../HTMLKit.docc/Plugins/ConverterPlugin.md | 17 ++ 54 files changed, 1285 insertions(+), 402 deletions(-) create mode 100644 Sources/HTMLKit/HTMLKit.docc/Essentials/GettingStarted.md delete mode 100644 Sources/HTMLKit/HTMLKit.docc/Essentials/Getting_started.md delete mode 100644 Sources/HTMLKit/HTMLKit.docc/Essentials/Parts/Elements.md delete mode 100644 Sources/HTMLKit/HTMLKit.docc/Essentials/Parts/Layouts.md delete mode 100644 Sources/HTMLKit/HTMLKit.docc/Essentials/Parts/Statements.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Essentials/VaporIntegration.md delete mode 100644 Sources/HTMLKit/HTMLKit.docc/Features/Conversion.md delete mode 100644 Sources/HTMLKit/HTMLKit.docc/Features/Localization.md delete mode 100644 Sources/HTMLKit/HTMLKit.docc/Features/Templating.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components/ActionButton.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components/CheckField.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components/Collection.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components/DatePicker.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components/Divider.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components/FieldLabel.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components/Form.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components/HStack.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components/Image.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components/Link.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components/List.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components/ProgressView.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components/RadioSelect.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components/ResetButton.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components/SearchField.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components/SecureField.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components/SelectField.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components/Slider.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components/Snippet.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components/SubmitButton.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components/Text.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components/TextEditor.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components/TextField.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components/Toggle.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components/VStack.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Components/ZStack.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Elements.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Globalization.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Globalization/Localization.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Statements.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Statements/Foreach.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Statements/Ifelse.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Statements/Unwrap.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Template.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Template/Annotations/TemplateValue.md rename Sources/HTMLKit/HTMLKit.docc/{Essentials/Parts => Framework/Template}/Context.md (62%) create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Template/Layouts.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Template/Layouts/Page.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Framework/Template/Layouts/View.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Plugins/ComponentsPlugin.md create mode 100644 Sources/HTMLKit/HTMLKit.docc/Plugins/ConverterPlugin.md diff --git a/README.md b/README.md index a481c4e4..9311d0c3 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@
avatar

HTMLKit

-

Render dynamic HTML templates in a typesafe and performant way! By using Swift's powerful language features and a pre-rendering algorithm, HTMLKit will render insanely fast templates but also catch bugs that otherwise might occur with other templating options.

+

Create and render HTML templates with HTMLKit.

- documentation + documentation versions diff --git a/Sources/HTMLKit/Framework/Core/Primitives/Layouts/Layouts.swift b/Sources/HTMLKit/Framework/Core/Primitives/Layouts/Layouts.swift index 511ba779..e57a35c1 100644 --- a/Sources/HTMLKit/Framework/Core/Primitives/Layouts/Layouts.swift +++ b/Sources/HTMLKit/Framework/Core/Primitives/Layouts/Layouts.swift @@ -4,19 +4,13 @@ */ /// A type that defines a page layout. -/// -/// The page covers the whole frame of a hompage. It can contain views and components. public protocol Page: AnyLayout, GlobalElement { } /// A type that defines a view layout. -/// -/// The view is a single part of page. It can contain views ad components. public protocol View: AnyLayout, GlobalElement { } /// A type that defines a component layout. -/// -/// The component is a partial part of a view or page. public protocol Component: AnyLayout, GlobalElement { } diff --git a/Sources/HTMLKit/HTMLKit.docc/Essentials/GettingStarted.md b/Sources/HTMLKit/HTMLKit.docc/Essentials/GettingStarted.md new file mode 100644 index 00000000..2c975fc2 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Essentials/GettingStarted.md @@ -0,0 +1,31 @@ +# Getting started + +Learn how to use the framework. + +> Important: The framework requires Swift 5.6 or higher. + +### Manifest + +To use the the framework in your project you need to add it to the package manifest first. + +```swift +let package = Package( + ... + dependencies: [ + // 1. Add the package + .package(url: "https://github.com/vapor-community/HTMLKit.git", from: "2.8.0"), + ], + targets: [ + .target( + ... + dependencies: [ + /// 2. Add the product + .product(name: "HTMLKit", package: "HTMLKit"), + ] + ), + ... + ] +) +``` + +Import the module in one of your files next. diff --git a/Sources/HTMLKit/HTMLKit.docc/Essentials/Getting_started.md b/Sources/HTMLKit/HTMLKit.docc/Essentials/Getting_started.md deleted file mode 100644 index 63d7fb56..00000000 --- a/Sources/HTMLKit/HTMLKit.docc/Essentials/Getting_started.md +++ /dev/null @@ -1,42 +0,0 @@ -# Getting started - -Learn how to use it. - -### Requirements - -HTMLKit requires Swift 5.6 or higher. - -### Installation - -To use HTMLKit in your project, you have to add the package as dependency to your package description first. Be sure to add it as your desired targets as well. - -```swift -let package = Package( - ... - dependencies: [ - // 1. Add the package - .package(url: "https://github.com/vapor-community/HTMLKit.git", from: "2.6.0"), - ], - targets: [ - .target( - ... - dependencies: [ - /// 2. Add the product - .product(name: "HTMLKit", package: "HTMLKit"), - ] - ), - ... - ] -) -``` - -From time to time you want to update the package. You can do it, by changing the version tag manually and saving it. You find the current version tag in the [release history](https://github.com/vapor-community/HTMLKit/releases). We recommand to read the release description first, to understand the possible changes. - -### Usage - -Use the import keyword to load the module in your project files. - -```swift -import HTMLKit -... -``` diff --git a/Sources/HTMLKit/HTMLKit.docc/Essentials/Parts/Elements.md b/Sources/HTMLKit/HTMLKit.docc/Essentials/Parts/Elements.md deleted file mode 100644 index 7d8448b7..00000000 --- a/Sources/HTMLKit/HTMLKit.docc/Essentials/Parts/Elements.md +++ /dev/null @@ -1,75 +0,0 @@ -# Elements - -## Overview - -The elements in HTMLKit represent the official HTML elements. Elements with content use the curly brackets, while elements without content use the round brackets. To add attributes to the element use the offered functions. - -### Definition - -```swift -/// element with content -Body { - ... -} - -/// element without content -Input() -``` - -### Attributes - -```swift -/// attribute with value -.class("value") - -/// attribute as toggle -.required() -``` - -### Modifier -```swift -/// modifies if the condition is true -Body { - ... -} -.modify(if: condition) { - $0.hidden() -} - -/// modifies if the value is set -Body { - ... -} -.modify(unwrap: value) { - $0.placeholder($1) -} -``` - -## Limitation - -To prevent invalid code, each element owns a element definition. For example the element `Heading1` is a type of `BodyElement`, so it is only allowed to be placed in the `Body` element. See the [wiki](https://github.com/vapor-community/HTMLKit/wiki) for more element definitions. - -```swift -public struct Heading1: ContentNode, BodyElement { - ... -} -``` - -```html - - -

headline

- - -

headline

- - -``` - -If you need to break the limitation, extend the element with the element definition of your choice or define it as `GlobalElement`. - -```swift -extension FormContainer: GlobalElement { - ... -} -``` diff --git a/Sources/HTMLKit/HTMLKit.docc/Essentials/Parts/Layouts.md b/Sources/HTMLKit/HTMLKit.docc/Essentials/Parts/Layouts.md deleted file mode 100644 index ab556a93..00000000 --- a/Sources/HTMLKit/HTMLKit.docc/Essentials/Parts/Layouts.md +++ /dev/null @@ -1,59 +0,0 @@ -# Layouts - -## Overview - -Layouts allow to define a website template. It is used to provide a consistend look. - -## Page - -The page is the entry point of the site. It should be used to package the views. - -```swift -struct SimplePage: Page { - - var body: AnyContent { - Document(type: .html5) - Html { - Head { - Title { - "SimplePage" - } - } - Body { - } - } - } -} -``` - -## View - -The view is a partial view of the page. It should be used to display data using the context. - -```swift -struct SimpleView: View { - - @TemplateValue(SimpleContext.self) - var context - - var body: AnyContent { - Heading1 { - context - } - } -} -``` - -The context as an object holds the information for the view. ... See [Context](https://github.com/vapor-community/HTMLKit/blob/master/Instructions/Essential/Context.md) to learn more about it. - -## Component - -The component is a reusable portion of a page. It should be used to break up large files into smaller components. - -```swift -struct SimpleComponent: Component { - - var body: AnyContent { - } -} -``` diff --git a/Sources/HTMLKit/HTMLKit.docc/Essentials/Parts/Statements.md b/Sources/HTMLKit/HTMLKit.docc/Essentials/Parts/Statements.md deleted file mode 100644 index a76088ca..00000000 --- a/Sources/HTMLKit/HTMLKit.docc/Essentials/Parts/Statements.md +++ /dev/null @@ -1,45 +0,0 @@ -# Statements - -## Overview - -### Branch Statements - -If - -```swift -IF(context.categories.isEmpty) { - Paragraph { - "There aren't any categories yet!" - } -} -.else { - ... -} -``` - -### Loop Statements - -ForEach - -```swift -ForEach(in: context.categories) { category in - Division { - Paragraph { - category.title - } - ... - } -} -``` - -### Optional Statements - -Unwrap - -```swift -Unwrap(category.content) { content in - Paragraph { - content - } -} -``` diff --git a/Sources/HTMLKit/HTMLKit.docc/Essentials/VaporIntegration.md b/Sources/HTMLKit/HTMLKit.docc/Essentials/VaporIntegration.md new file mode 100644 index 00000000..897005b3 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Essentials/VaporIntegration.md @@ -0,0 +1,45 @@ +# Vapor integration + +Use the framework together with Vapor. + +## Overview + +The HTMLKit framework uses the web framework [Vapor](https://swiftpackageindex.com/vapor/vapor) as its standard view renderer. + +### Configure + +Before you can use the view renderer, you need to do some adjustments in the *configure.swift* file of your Vapor project: + +```swift +/// 1. Load the module +import HTMLKitVapor +import Vapor + +public func configure(_ app: Application) throws { + + /// 2. Specify the view renderer + app.views.use(.htmlkit) + + /// 3. Add the layout + app.htmlkit.views.add(view: ExampleTemplate.ExampleView()) + + try routes(app) +} +``` + +### Request + +Now you can call the method *render* on the request in one of your controllers: + +```swift +import Vapor + +final class ExampleController { + + func getIndex(_ request: Request) async throws -> View { + + /// 1. Name the layout + return try await request.view.render("ExampleTemplate.IndexView") + } +} +``` diff --git a/Sources/HTMLKit/HTMLKit.docc/Features/Conversion.md b/Sources/HTMLKit/HTMLKit.docc/Features/Conversion.md deleted file mode 100644 index d7c3bde9..00000000 --- a/Sources/HTMLKit/HTMLKit.docc/Features/Conversion.md +++ /dev/null @@ -1,48 +0,0 @@ -# Conversion - -Use conversion - -## Overview - -With HTMLKit you can convert your existing HTML code into Swift. It makes the change easier, faster and it can give you an idea how the library works. - -### Call - -Call the converter and use the convert function. Pass the directory, where your html files are located and choose the output. We recommend to use the print option first, to get a quick preview on the output. The print shows up in the debug window of your IDE. If you choose the file option, the converter creates the swift files at the same directory you have given to the converter. - -```swift -/// creates the output as file -try Converter.default.convert(directory: directory, extension: .html, option: .file) - -/// prints the output -try Converter.default.convert(directory: directory, extension: .html, option: .print) -``` - -### Input - -```html - - - -``` - -### Output - -```swift -import HTMLKit - -struct IndexPage: Page { - - public var body: AnyContent { - Document(type: .html5) - Html { - } - .language(.english) - - } -} -``` - -## Note - -Keep in mind, that maybe the converter has not covered every case. If you miss something, file an [issue](https://github.com/vapor-community/HTMLKit/issues) and let us know to make the converter better. diff --git a/Sources/HTMLKit/HTMLKit.docc/Features/Localization.md b/Sources/HTMLKit/HTMLKit.docc/Features/Localization.md deleted file mode 100644 index 92433a9e..00000000 --- a/Sources/HTMLKit/HTMLKit.docc/Features/Localization.md +++ /dev/null @@ -1,59 +0,0 @@ -# Localization - -Use localization - -## Overview - -HTMLKit can render your content in different languages by using Localization. - -### Registration - -The localization is optional, so if you want to use it, you need to register it first. Pass the directory path and the local identifier to the renderer. Keep in mind, that the directory path is the root directory where your localization files are located. - -```swift -try app.htmlkit.renderer.registerLocalization(atPath: path, defaultLocale: "en") -``` - -### Definition - -Define your localizations in a .json file. If you want to get to know more about definitions, take a a look at the [Lingo library](https://github.com/miroslavkovac/Lingo#usage). - -```json -{ - "Hallo.Welt": "Hello World" -} -``` - -### Implementation - -You can retrieve the definition by calling the localized initialiser of a localizable element. Most of the phrasing elements in HTMLKit should be localizable and provide you with the specific initialiser. Please [open an issue](https://github.com/vapor-community/HTMLKit/issues), if you find an element without it. - -```swift -struct IndexView: View { - - var body: AnyContent { - Article { - Heading1("Hallo.Welt") - } - } -} -``` - -Also the locale for the environment can be changed for example by user input. Use the environment modifier on the element and pass the specific local identifier for it. - -```swift -struct IndexView: View { - - struct Context { - let date: Date - let locale: String - } - - var body: AnyContent { - Article { - ... - } - .environment(locale: context.locale) - } -} -``` diff --git a/Sources/HTMLKit/HTMLKit.docc/Features/Templating.md b/Sources/HTMLKit/HTMLKit.docc/Features/Templating.md deleted file mode 100644 index f03f6895..00000000 --- a/Sources/HTMLKit/HTMLKit.docc/Features/Templating.md +++ /dev/null @@ -1,55 +0,0 @@ -# Templating - -## Overview - -### Embed - -You can embed the view in the page structure. - -```swift -struct SimplePage: Page { - - var body: AnyContent { - Document(type: .html5) - Head { - Title { - "SimplePage" - } - } - Body { - SimpleView(context: "Hello World!") - } - } -} -``` - -### Extend - -You can extend the page in the view structure. - -```swift -struct IndexView: View { - - var body: AnyContent { - SimplePage { - Heading1 { - "Hello World!" - } - } - } -} -``` - -### Output - -```html - - - - SimplePage - - -

Hello World!

- - -``` diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components.md new file mode 100644 index 00000000..c49a9e74 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components.md @@ -0,0 +1,74 @@ +# Components + +Construct UI interfaces using the components. + +## Overview + +The components library follows the idea of a complete design system. It offers you standardized, reusable components imitating the syntax and semantic of SwiftUI. The library also comes with CSS (Cascading Style Sheet) to help you constructing your vision, without the need to completely rebuild it or furthermore any knowledge in CSS. + +```swift +HStack { + StackColumn(size: .twelve) { + Paragraph { + "Lorem ipsum..." + } + } +} +``` + +```css +.hstack { + position: relative; + width: 100%; + height: 100%; + display: flex; + flex-direction: row; + flex-wrap: nowrap; +} +``` + +## Topics + +### Form components + +- +- +- +- +- +- +- +- +- +- +- +- +- +- + +### List components + +- +- + +### Section components + +- +- +- +- + +### Text components + +- + +### Link components + +- +- + +### Media components + +- +- +- diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components/ActionButton.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/ActionButton.md new file mode 100644 index 00000000..e830ce61 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/ActionButton.md @@ -0,0 +1,27 @@ +# ActionButton + +A component that initiates an action. + +## Declaration + +```swift +struct ActionButton : Component +``` + +## Overview + +```swift +ActionButton(destination: "/home") { + "Home" +} +``` + +## Modifiers + +- func buttonSize(_ size: Tokens.ButtonSize) + +- func borderShape(_ shape: Tokens.BorderShape) + +- func buttonStyle(_ style: Tokens.ButtonStyle) + +- func backgroundColor(_ color: Tokens.BackgroundColor) diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components/CheckField.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/CheckField.md new file mode 100644 index 00000000..66c652d2 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/CheckField.md @@ -0,0 +1,21 @@ +# CheckField + +A component for selecting one or multiple options. + +## Declaration + +```swift +struct CheckField : Component +``` + +## Overview + +```swift +CheckField(name:, value:) +``` + +## Modifiers + +- func borderShape(_ shape: Tokens.BorderShape) + +- func backgroundColor(_ color: Tokens.BackgroundColor) diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Collection.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Collection.md new file mode 100644 index 00000000..4cff1345 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Collection.md @@ -0,0 +1,23 @@ +# Collection + +A component to collect and arrange collection items horizontally. + +## Declaration + +```swift +struct Collection : Component +``` + +## Overview + +```swift +Collection(ratio: .half) { + CollectionItem { + Image(source: "../assets/thumbnail.png") + } +} +``` + +### Modifiers + +- collectionStyle(_ style: Token.CollectionStyle) diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components/DatePicker.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/DatePicker.md new file mode 100644 index 00000000..37dc4b63 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/DatePicker.md @@ -0,0 +1,21 @@ +# DatePicker + +A component for selecting a specific date and year. + +## Declaration + +```swift +struct DatePicker : Component +``` + +## Overview + +```swift +DatePicker(name: "release") +``` + +## Modifiers + +- func borderShape(_ shape: Tokens.BorderShape) + +- func backgroundColor(_ color: Tokens.BackgroundColor) diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Divider.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Divider.md new file mode 100644 index 00000000..3663a3ec --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Divider.md @@ -0,0 +1,15 @@ +# Divider + +A component to seperate content visually. + +## Declaration + +```swift +struct Divider : Component +``` + +## Overview + +```swift +Divider() +``` diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components/FieldLabel.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/FieldLabel.md new file mode 100644 index 00000000..b612c799 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/FieldLabel.md @@ -0,0 +1,17 @@ +# FieldLabel + +A component that displays the name of the form control. + +## Declaration + +```swift +struct FieldLabel : Component +``` + +## Overview + +```swift +FieldLabel(for: "firstname") { + "Firstname" +} +``` diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Form.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Form.md new file mode 100644 index 00000000..79f0cf03 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Form.md @@ -0,0 +1,20 @@ +# Form + +A component that collects form controls. + +## Declaration + +```swift +struct Form : Component +``` + +## Overview + +```swift +Form { + FieldLabel(name: "firstname") { + "Firstname" + } + TextField(name: "firstname") +} +``` diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components/HStack.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/HStack.md new file mode 100644 index 00000000..fc163bb2 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/HStack.md @@ -0,0 +1,29 @@ +# HStack + +A component to arrange content horizontally. + +## Declaration + +```swift +struct HStack : Component +``` + +## Overview + +```swift +HStack(alignment: .center) { + StackColumn(size: .twelve) { + Text { + "Lorem ipsum..." + } + } +} +``` + +## Modifiers + +- func backgroundColor(_ color: Tokens.BackgroundColor) + +- func opacity(_ value: Tokens.OpacityValue) + +- func zIndex(_ index: Tokens.PositionIndex) diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Image.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Image.md new file mode 100644 index 00000000..84ba8c53 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Image.md @@ -0,0 +1,29 @@ +# Image + +A component that displays a image. + +## Declaration + +```swift +struct Image : Component +``` + +## Overview + +```swift +Image(source: "../assets/thumbnail.png" ) +``` + +## Modifiers + +- func objectFit(_ fit: Tokens.ObjectFit) + +- func imageScale(_ scale: Tokens.ImageScale) + +- func clipShape(_ shape: Tokens.ClipShape) + +- func backgroundColor(_ color: Tokens.BackgroundColor) + +- func zIndex(_ index: Tokens.PositionIndex) + +- func opacity(_ value: Tokens.OpacityValue) diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Link.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Link.md new file mode 100644 index 00000000..4a8bd348 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Link.md @@ -0,0 +1,37 @@ +# Link + +A component that navigates to an target. + +## Declaration + +```swift +struct Link : Component +``` + +## Overview + +```swift +Link(destination: "/home") { + "Home" +} +``` + +## Modifiers + +- func font(_ style: Tokens.TextStyle) + +- func foregroundColor(_ color: Tokens.ForegroundColor) + +- fontSize(_ size: Tokens.FontSize) + +- func fontWeight(_ weight: Tokens.FontWeight) + +- func fontTransformation(_ transformation: Tokens.TextTransformation) + +- fontStyle(_ style: Tokens.FontStyle) + +- func bold() + +- func italic() + +- underline() diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components/List.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/List.md new file mode 100644 index 00000000..6f4e0a65 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/List.md @@ -0,0 +1,25 @@ +# List + +A component to collect and arrange list items vertically. + +## Declaration + +```swift +struct List : Component +``` + +## Overview + +```swift +List(direction: .vertical) { + ListRow { + Text { + "Lorem ipsum..." + } + } +} +``` + +## Modifiers + +- func listStyle(_ style: Tokens.ListStyle) diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components/ProgressView.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/ProgressView.md new file mode 100644 index 00000000..e114ce60 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/ProgressView.md @@ -0,0 +1,16 @@ +# ProgressView + +A component to display the progress of a task. + +## Declaration + +```swift +struct ProgressView : Component +``` + +## Overview + +```swift +ProgressView(name: "delivery") { +} +``` diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components/RadioSelect.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/RadioSelect.md new file mode 100644 index 00000000..248a2a20 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/RadioSelect.md @@ -0,0 +1,21 @@ +# RadioSelect + +A component for selecting only one of multiple options. + +## Declaration + +```swift +struct RadioSelect : Component +``` + +## Overview + +```swift +RadioSelect(name:, value:) +``` + +## Modifiers + +- func borderShape(_ shape: Tokens.BorderShape) + +- func backgroundColor(_ color: Tokens.BackgroundColor) diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components/ResetButton.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/ResetButton.md new file mode 100644 index 00000000..8972fdfe --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/ResetButton.md @@ -0,0 +1,27 @@ +# ResetButton + +A component that initiates a form reset. + +## Declaration + +```swift +struct ResetButton : Component +``` + +## Overview + +```swift +ResetButton { + "Reset" +} +``` + +## Modifiers + +- func buttonSize(_ size: Tokens.ButtonSize) + +- func borderShape(_ shape: Tokens.BorderShape) + +- func buttonStyle(_ style: Tokens.ButtonStyle) + +- func backgroundColor(_ color: Tokens.BackgroundColor) diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components/SearchField.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/SearchField.md new file mode 100644 index 00000000..21b79f6a --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/SearchField.md @@ -0,0 +1,21 @@ +# SearchField + +A component to initiate a search or filter. + +## Declaration + +```swift +struct SearchField : Component +``` + +## Overview + +```swift +SearchField(name: "search") +``` + +## Modifiers + +- func borderShape(_ shape: Tokens.BorderShape) + +- func backgroundColor(_ color: Tokens.BackgroundColor) diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components/SecureField.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/SecureField.md new file mode 100644 index 00000000..fca2f16d --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/SecureField.md @@ -0,0 +1,21 @@ +# SecureField + +A component to enter sensitive information. + +## Declaration + +```swift +struct SecureField : Component +``` + +## Overview + +```swift +SecureField(name: "password") +``` + +## Modifiers + +- func borderShape(_ shape: Tokens.BorderShape) + +- func backgroundColor(_ color: Tokens.BackgroundColor) diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components/SelectField.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/SelectField.md new file mode 100644 index 00000000..2542702e --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/SelectField.md @@ -0,0 +1,22 @@ +# SelectField + +A component for selecting one or multiple options. + +## Declaration + +```swift +struct SelectField : Component +``` + +## Overview + +```swift +SelectField(name: "category") { +} +``` + +## Modifiers + +- func borderShape(_ shape: Tokens.BorderShape) + +- func backgroundColor(_ color: Tokens.BackgroundColor) diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Slider.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Slider.md new file mode 100644 index 00000000..91ee1ccc --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Slider.md @@ -0,0 +1,15 @@ +# Slider + +A component for selecting a value within a given range. + +## Declaration + +```swift +struct Slider : Component +``` + +## Overview + +```swift +Slider(name:) +``` diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Snippet.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Snippet.md new file mode 100644 index 00000000..ae129f5c --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Snippet.md @@ -0,0 +1,19 @@ +# Snippet + +A component to display code content. + +## Declaration + +```swift +struct Snippet : Component +``` + +## Overview + +```swift +Snippet(language: .css) { + .body { + background-color: black; + } +} +``` diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components/SubmitButton.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/SubmitButton.md new file mode 100644 index 00000000..e303d73f --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/SubmitButton.md @@ -0,0 +1,27 @@ +# SubmitButton + +A component that initiates a form submit. + +## Declaration + +```swift +struct SubmitButton : Component +``` + +## Overview + +```swift +SubmitButton { + "Submit" +} +``` + +## Modifiers + +- func buttonSize(_ size: Tokens.ButtonSize) + +- func borderShape(_ shape: Tokens.BorderShape) + +- func buttonStyle(_ style: Tokens.ButtonStyle) + +- func backgroundColor(_ color: Tokens.BackgroundColor) diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Text.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Text.md new file mode 100644 index 00000000..7c0b5490 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Text.md @@ -0,0 +1,37 @@ +# Text + +A component that displays text. + +## Declaration + +```swift +struct Text : Component +``` + +## Overview + +```swift +Text { + "Lorem ipsum..." +} +``` + +## Modifiers + +- func font(_ style: Tokens.TextStyle) + +- func foregroundColor(_ color: Tokens.ForegroundColor) + +- fontSize(_ size: Tokens.FontSize) + +- func fontWeight(_ weight: Tokens.FontWeight) + +- func fontTransformation(_ transformation: Tokens.TextTransformation) + +- fontStyle(_ style: Tokens.FontStyle) + +- func bold() + +- func italic() + +- underline() diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components/TextEditor.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/TextEditor.md new file mode 100644 index 00000000..c13007b9 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/TextEditor.md @@ -0,0 +1,25 @@ +# TextEditor + +A component that displays a editable and expandable form control. + +## Declaration + +```swift +struct TextEditor : Component +``` + +## Overview + +```swift +TextEditor(name: "description") { + "Lorem ipsum..." +} +``` + +## Modifiers + +- func lineLimit(_ value: Int) + +- func borderShape(_ shape: Tokens.BorderShape) + +- func backgroundColor(_ color: Tokens.BackgroundColor) diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components/TextField.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/TextField.md new file mode 100644 index 00000000..3e487527 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/TextField.md @@ -0,0 +1,21 @@ +# TextField + +A component that displays an editable form control. + +## Declaration + +```swift +struct TextField : Component +``` + +## Overview + +```swift +TextField(name: "firstname") +``` + +## Modifiers + +- func borderShape(_ shape: Tokens.BorderShape) + +- func backgroundColor(_ color: Tokens.BackgroundColor) diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Toggle.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Toggle.md new file mode 100644 index 00000000..f37c5eda --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/Toggle.md @@ -0,0 +1,15 @@ +# Toggle + +A component that shows an on or off state. + +## Declaration + +```swift +struct Toggle : Component +``` + +## Overview + +```swift +Toggle(name:) +``` diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components/VStack.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/VStack.md new file mode 100644 index 00000000..cfcff1e6 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/VStack.md @@ -0,0 +1,29 @@ +# VStack + +A component to arrange content vertically. + +## Declaration + +```swift +struct VStack : Component +``` + +## Overview + +```swift +VStack(alignment: .leading) { + StackColumn(size: .twelve) { + Text { + "Lorem ipsum..." + } + } +} +``` + +## Modifiers + +- func backgroundColor(_ color: Tokens.BackgroundColor) + +- func opacity(_ value: Tokens.OpacityValue) + +- func zIndex(_ index: Tokens.PositionIndex) diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Components/ZStack.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/ZStack.md new file mode 100644 index 00000000..91167ea2 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Components/ZStack.md @@ -0,0 +1,24 @@ +# ZStack + +A component that overlays content. + +## Declaration + +```swift +struct ZStack : Component +``` + +## Overview + +```swift +ZStack { +} +``` + +## Modifiers + +- func backgroundColor(_ color: Tokens.BackgroundColor) + +- func opacity(_ value: Tokens.OpacityValue) + +- func zIndex(_ index: Tokens.PositionIndex) diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Elements.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Elements.md new file mode 100644 index 00000000..57321240 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Elements.md @@ -0,0 +1,182 @@ +# Elements + +Write HTML markup using the abstraction. + +## Overview + +The elements in HTMLKit are an abstraction of the elements in HTML (Hyper Text Markup Language). If you have written HTML before, then you know, there are elements with or without an endtag. An Element with an end tag, will be represented in HTMLKit as an element with curly brackets, while an element without will be represented with the round brackets. + +If you would like to add attributes, use the offered methods on the element. In most cases the method name matches the attribute name in HTML. + +```swift +/// element with content +Body { + Paragraph { + "Lorem ipsum..." + } + .class("value") +} + +/// element without content +Input() + .required() +``` + +To prevent writing invalid code, each element in HTMLKit owns an element limitation. For example the element *Heading1* is a type of *BodyElement*, so it is only valid as content of a body element. + +```swift +public struct Heading1: ContentNode, BodyElement { + ... +} +``` + +```html + + +

headline

+ + +

headline

+ + +``` + +If you need to break up the limitation, extend the element with the element protocol of your choice or define it as `GlobalElement`. + +```swift +extension FormContainer: GlobalElement { + ... +} +``` + +## Topics + +### Basic elements + +- ``HTMLKit/Html`` + +- ``HTMLKit/Head`` + +- ``HTMLKit/Body`` + +### Head elements + +- ``HTMLKit/Title`` + +- ``HTMLKit/Meta`` + +- ``HTMLKit/Style`` + +- ``HTMLKit/Base`` + +- ``HTMLKit/Link`` + +### Flow elements + +- ``HTMLKit/Header`` + +- ``HTMLKit/Main`` + +- ``HTMLKit/Division`` + +- ``HTMLKit/Section`` + +- ``HTMLKit/Navigation`` + +- ``HTMLKit/Aside`` + +- ``HTMLKit/Footer`` + +### Paragraph elements + +- ``HTMLKit/Heading1`` + +- ``HTMLKit/Heading2`` + +- ``HTMLKit/Heading3`` + +- ``HTMLKit/Heading4`` + +- ``HTMLKit/Heading5`` + +- ``HTMLKit/Heading6`` + +- ``HTMLKit/Paragraph`` + +- ``HTMLKit/Bold`` + +- ``HTMLKit/Italic`` + +- ``HTMLKit/Underline`` + +- ``HTMLKit/Emphasize`` + +- ``HTMLKit/Small`` + +- ``HTMLKit/Strong`` + +### List elements + +- ``HTMLKit/UnorderedList`` + +- ``HTMLKit/OrderedList`` + +- ``HTMLKit/ListItem`` + +### Table elements + +- ``HTMLKit/Table`` + +- ``HTMLKit/TableHead`` + +- ``HTMLKit/TableBody`` + +- ``HTMLKit/TableFoot`` + +- ``HTMLKit/TableRow`` + +- ``HTMLKit/HeaderCell`` + +- ``HTMLKit/DataCell`` + +### Form elements + +- ``HTMLKit/Form`` + +- ``HTMLKit/Label`` + +- ``HTMLKit/Input`` + +- ``HTMLKit/TextArea`` + +- ``HTMLKit/Select`` + +- ``HTMLKit/Button`` + +- ``HTMLKit/Fieldset`` + +### Media elements + +- ``HTMLKit/Audio`` + +- ``HTMLKit/Video`` + +### Vector elements + +- ``HTMLKit/Circle`` + +- ``HTMLKit/Rectangle`` + +- ``HTMLKit/Ellipse`` + +- ``HTMLKit/Line`` + +- ``HTMLKit/Polygon`` + +- ``HTMLKit/Polyline`` + +- ``HTMLKit/Path`` + +- ``HTMLKit/Group`` + +- ``HTMLKit/Use`` diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Globalization.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Globalization.md new file mode 100644 index 00000000..8c6e68c9 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Globalization.md @@ -0,0 +1,43 @@ +# Globalization + +Localize your content for a wider audience. + +## Overview + +The framework uses the localization framework [Lingo](https://swiftpackageindex.com/miroslavkovac/Lingo) to translate and formate the content by local language and culture. + +### Configure + +Before you can use the localization, you need to set it up in the *configure.swift* file of your Vapor project: + +```swift +import HTMLKitVapor +import Vapor + +public func configure(_ app: Application) throws { + + /// 1. Specify the directory path + app.htmlkit.lingo.set(directory: currentDirectory) + + /// 2. Specify the default language + app.htmlkit.lingo.set(locale: .english) + + try routes(app) +} +``` + +### Message file + +Next you have to create a message file (for example en.json), wich contains the the translations strings for the given language. + +```json +{ + "Hallo Welt": "Hello World" +} +``` + +## Topics + +### Localization + +- diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Globalization/Localization.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Globalization/Localization.md new file mode 100644 index 00000000..35eeaecb --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Globalization/Localization.md @@ -0,0 +1,34 @@ +# ``HTMLKit/Localization`` + +@Metadata { + @DocumentationExtension(mergeBehavior: append) +} + +```swift +struct IndexView: View { + + var body: AnyContent { + Article { + Heading1("Hallo.Welt") + } + } +} +``` + +Also the locale for the environment can be changed for example by user input. Use the environment modifier on the element and pass the specific local identifier for it. + +```swift +struct IndexView: View { + + struct Context { + let date: Date + let locale: String + } + + var body: AnyContent { + Article { + ... + } + .environment(locale: context.locale) + } +} diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Statements.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Statements.md new file mode 100644 index 00000000..06967d70 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Statements.md @@ -0,0 +1,29 @@ +# Statements + +Control the flow of your content using statements. + +## Overview + +Similar to other frameworks there exit various statements to control the flow of your content. Use the branch statements to perfom certain code depending on a condition, run through a sequence using the loop statements or unwrap an optional value with the optional statements. + +```swift +ForEach(in: fruits) { fruit in + Paragraph { + fruit.name + } +} +``` + +## Topics + +### Branch Statements + +- + +### Loop Statements + +- + +### Optional Statements + +- diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Statements/Foreach.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Statements/Foreach.md new file mode 100644 index 00000000..cd874627 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Statements/Foreach.md @@ -0,0 +1,16 @@ +# ``HTMLKit/ForEach`` + +@Metadata { + @DocumentationExtension(mergeBehavior: append) +} + +```swift +ForEach(in: context.categories) { category in + Division { + Paragraph { + category.title + } + ... + } +} +``` diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Statements/Ifelse.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Statements/Ifelse.md new file mode 100644 index 00000000..ec75217f --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Statements/Ifelse.md @@ -0,0 +1,5 @@ +# ``HTMLKit/IF`` + +@Metadata { + @DocumentationExtension(mergeBehavior: append) +} diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Statements/Unwrap.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Statements/Unwrap.md new file mode 100644 index 00000000..2dcd4e6f --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Statements/Unwrap.md @@ -0,0 +1,13 @@ +# ``HTMLKit/Unwrap`` + +@Metadata { + @DocumentationExtension(mergeBehavior: append) +} + +```swift +Unwrap(category.content) { content in + Paragraph { + content + } +} +``` diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Template.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Template.md new file mode 100644 index 00000000..cb3685ed --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Template.md @@ -0,0 +1,34 @@ +# Template + +Scaffold your written content and apply context. + + +## Overview + +In HTMLKit a template consist of two parts. The first part is the view logic, wich gives the template the structure to display the content as you want. The second part is the data logic, wich gives the template the data to process the variables, that you may set in between the content. + +```swift +struct SimpleView: View { + + @TemplateValue(String.self) + var context + + var body: AnyContent { + SimplePage { + Heading1 { + context + } + } + } +} +``` + +## Topics + +### View logic + +- + +### Data logic + +- diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Template/Annotations/TemplateValue.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Template/Annotations/TemplateValue.md new file mode 100644 index 00000000..52ba2ef6 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Template/Annotations/TemplateValue.md @@ -0,0 +1,5 @@ +# TemplateValue + +@Metadata { + @DocumentationExtension(mergeBehavior: append) +} diff --git a/Sources/HTMLKit/HTMLKit.docc/Essentials/Parts/Context.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Template/Context.md similarity index 62% rename from Sources/HTMLKit/HTMLKit.docc/Essentials/Parts/Context.md rename to Sources/HTMLKit/HTMLKit.docc/Framework/Template/Context.md index 2c9c6698..64c63eca 100644 --- a/Sources/HTMLKit/HTMLKit.docc/Essentials/Parts/Context.md +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Template/Context.md @@ -1,7 +1,11 @@ # Context +Add data to your template. + ## Overview +The context holds the data for the content variables, wich get replaced when the template is evaulated. + ```swift struct SimpleContext: Codable { @@ -23,3 +27,9 @@ struct SimpleView: View { } } ``` + +## Topics + +### Annotations + +- ``HTMLKit/TemplateValue`` diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Template/Layouts.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Template/Layouts.md new file mode 100644 index 00000000..8c227cad --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Template/Layouts.md @@ -0,0 +1,51 @@ +# Layouts + +Embed or extend views to create a layout. + + +## Overview + +There will be situations, where you would like to use certain views at multiple places in your project and that's where the layout system comes in handy. You can embed the view in another or extend the view to be used for a different view. + +### Embed the view + +```swift +struct SimplePage: Page { + + var body: AnyContent { + Document(type: .html5) + Head { + Title { + "SimplePage" + } + } + Body { + SimpleView(context: "Hello World!") + } + } +} +``` + +### Extend the page + +```swift +struct SimpleView: View { + + var context: String + + var body: AnyContent { + SimplePage { + Heading1 { + context + } + } + } +} +``` + +## Topics + +### Layouts + +- +- diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Template/Layouts/Page.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Template/Layouts/Page.md new file mode 100644 index 00000000..98e1ac26 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Template/Layouts/Page.md @@ -0,0 +1,25 @@ +# ``HTMLKit/Page`` + +@Metadata { + @DocumentationExtension(mergeBehavior: append) +} + +A page is a container that holds the views. You create a page by declaring a type that conforms to the Page protocol. + +```swift +struct ExamplePage: Page { + + var body: AnyContent { + Document(.html5) + Html { + Head { + Title { + "ExamplePage" + } + } + Body { + } + } + } +} +``` diff --git a/Sources/HTMLKit/HTMLKit.docc/Framework/Template/Layouts/View.md b/Sources/HTMLKit/HTMLKit.docc/Framework/Template/Layouts/View.md new file mode 100644 index 00000000..17ec1335 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Framework/Template/Layouts/View.md @@ -0,0 +1,18 @@ +# ``HTMLKit/View`` + +@Metadata { + @DocumentationExtension(mergeBehavior: append) +} + +A view is a single part of a page. You create a view by declaring a type that conforms to the View protocol. + +```swift +struct ExampleView: View { + + var body: AnyContent { + Heading1 { + "Lorem ipsum..." + } + } +} +``` diff --git a/Sources/HTMLKit/HTMLKit.docc/HTMLKit.md b/Sources/HTMLKit/HTMLKit.docc/HTMLKit.md index 32c634e6..d647941e 100644 --- a/Sources/HTMLKit/HTMLKit.docc/HTMLKit.md +++ b/Sources/HTMLKit/HTMLKit.docc/HTMLKit.md @@ -1,26 +1,47 @@ # ``HTMLKit`` +Create and render HTML templates. + + ## Overview -- DSL (domain specific language) -- Pre-Rendering -- Templating +The HTMLKit framework consists a list of features to create HTML templates in a type-safe and performant way: + + +- **Declarative syntax** - The declarative syntax helps you write valid HTML markup. + +- **Template system** - You can scaffold your written code into various, reusable layouts to create an entire template. + +- **Dynamic context** - Apply context to your template to process content dynamically. + +- **Preprocess content** - The static content of the template will be preprocessed, to spare time and performance, when the template is executed. + +- **Language localization** - Specify the parts of the template, that should be translated or formatted for local languages and cultures. + +- **UI components** - Construct user interfaces with the components library. + + +## Integration + +The framework comes with an intergration for the web framework [Vapor](https://swiftpackageindex.com/vapor/vapor). + ## Topics ### Essentials -- +- +- -### Parts +### Framework -- - -- +- - +- +- -### Features +### Plugins -- -- -- +- +- diff --git a/Sources/HTMLKit/HTMLKit.docc/Plugins/ComponentsPlugin.md b/Sources/HTMLKit/HTMLKit.docc/Plugins/ComponentsPlugin.md new file mode 100644 index 00000000..857f1acc --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Plugins/ComponentsPlugin.md @@ -0,0 +1,15 @@ +# Use the components + +Deploys the CSS files + +## Overview + +The framework comes with a plugin, wich minifies and deploys the CSS files of the components into the public directory of your Vapor project. + +### Command + +Use the following command in your terminal: + +```sh +swift package --allow-writing-to-package-directory deploy +``` diff --git a/Sources/HTMLKit/HTMLKit.docc/Plugins/ConverterPlugin.md b/Sources/HTMLKit/HTMLKit.docc/Plugins/ConverterPlugin.md new file mode 100644 index 00000000..e425cfa0 --- /dev/null +++ b/Sources/HTMLKit/HTMLKit.docc/Plugins/ConverterPlugin.md @@ -0,0 +1,17 @@ +# Use conversion + +Converts HTML markup + +## Overview + +The framework comes with a plugin, wich converts HTML markup into the HTMLKit syntax. It makes the change to the framework way easier and faster. + +### Command + +Use the following command in your terminal: + +```sh +swift package --allow-writing-to-package-directory convert --source-path [source-path] --target-path [target-path] --output-option debug +``` + +As output option, you can choose between _file_ or _debug_. The option _file_ writes the output at the target path, while the option _debug_ prints it into the terminal.