Merge pull request #3 from angrybayblade/docs/django

Update Django documentation
angrybayblade · Mar 9, 2024 · d83f616 · d83f616
2 parents f16ea63 + b9464a7
commit d83f616
Show file tree

Hide file tree

Showing 13 changed files with 345 additions and 69 deletions.
diff --git a/README.md b/README.md
@@ -9,8 +9,11 @@
 ```
 pip3 install ph7
 ```
+
 ## Quickstart
+
 Write your first block of markup
+
 <!-- {"type": "html", "file": "examples/hello.py"} -->
 ```python
 from ph7.html import body, div, html
@@ -35,6 +38,72 @@ print(template)
 ```
 <!-- end -->
 
+Or write a CSS class
+
+<!-- {"type": "css", "file": "examples/css_example.py"} -->
+```python
+from ph7.css import CSSObject
+
+
+class flex_center(CSSObject):
+    """Flex center"""
+
+    display = "flex"
+    align_items = "center"
+    justify_content = "center"
+
+
+print(flex_center())
+```
+
+```css
+.flex-center {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+```
+<!-- end -->
+
+Or use python function as JavaScript functions
+
+
+<!-- {"type": "js", "file": "examples/js_example.py"} -->
+```python
+from ph7.js import as_js, console, document, fetch
+
+
+async def fetchDog():
+    response = await fetch(
+        "https://dog.ceo/api/breeds/image/random",
+        {"method": "GET"},
+    )
+    if response.status != 200:
+        response_body = await response.text()
+        console.log(f"Error fetching dog; {response_body}")
+        return
+    data = await response.json()
+    document.getElementById("image").src = data.message
+
+
+print(as_js(fetchDog))
+```
+
+```js
+async function fetchDog() {
+  let response = await fetch('https://dog.ceo/api/breeds/image/random', {
+    'method': 'GET'
+  });
+  if (response.status != 200) {
+    let response_body = await response.text();
+    console.log('Error fetching dog; ' + response_body);
+    return;
+  };
+  let data = await response.json();
+  document.getElementById('image').src = data.message;
+};
+```
+<!-- end -->
 
 Links:
 

diff --git a/docs/django.md b/docs/django.md
@@ -14,7 +14,7 @@ TEMPLATES = [
 ]
 ```
 
-## Write Templates
+## Templates
 
 ```bash
 |_ home
@@ -60,6 +60,60 @@ def home(request):
 If you name your view anything other than `template`, you can specify the view name using `module:view` format. For example if you name your view `home`, you can specify the template as `app:home`.
 
 
+
+## Forms
+
+Forms can be included directly using `form` tag.
+
+<!-- {"type": "html", "file": "examples/django_app/forms/templates/__init__.py", "input_only": true} -->
+```python
+from django import forms
+
+from ph7.html import body, div, form, html, title
+
+
+class UserForm(forms.Form):
+    """User form class."""
+
+    name = forms.CharField(label="username")
+    email = forms.EmailField(label="email")
+    password = forms.CharField(label="password", widget=forms.PasswordInput())
+
+
+template = html(
+    title("Forms Example"),
+    body(
+        div(
+            form(
+                UserForm(),
+            ),
+        )
+    ),
+)
+```
+
+<!-- end -->
+
+```html
+<html>
+    <head>
+        <title>Forms example</title>
+    </head>
+    <body>
+        <div>
+            <form>
+                <label for="id_name">username:</label>
+                <input type="text" name="name" required="" id="id_name">
+                <label for="id_email">email:</label>
+                <input type="email" name="email" maxlength="320" required="" id="id_email">
+                <label for="id_password">password:</label>
+                <input type="password" name="password" required="" id="id_password">
+            </form>
+        </div>
+    </body>
+</html>
+```
+
 ## Stylesheets
 
 Define your stylesheet using [`CSSObject`](/css/#cssobject) and use [`Static Context`](/css/#static-context) to include the stylesheets in your views. First let's define `templates/styles.py`
@@ -70,6 +124,10 @@ from ph7.css import CSSObject
 
 
 class main(CSSObject):
+    display = "flex"
+    align_items = "center"
+    justify_content = "center"
+
     height = "100vh"
     width = "100vw"
 
@@ -108,58 +166,145 @@ template = html(
 
 <!-- end -->
 
-> Note: In the final render of the stylesheet generated by static context, only the classes which have been used in a template will be included.
+This is what the rendered view looks like
 
+```html
+<html>
+  <head>
+    <title>Static Files Example</title>
+    <link
+      href="/static/css/static_files_templates_styles.css"
+      rel="stylesheet"
+      id="css.static_files.templates.styles"
+    />
+  </head>
+  <body>
+    <div class="main">Hello, World!</div>
+  </body>
+</html>
+```
 
-## Forms
+And this is what the rendered stylesheet looks like
+
+```css
+.main {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 100vh;
+  width: 100vw;
+  box-sizing: border-box;
+  margin: 0px;
+  padding: 0px;
+}
+```
 
-Forms can be included directly using `form` tag.
+> Note: In the final render of the stylesheet generated by static context, only the classes which have been used in a template will be included.
 
-<!-- {"type": "html", "file": "examples/django_app/forms/templates/__init__.py", "input_only": true} -->
+## Scripts
+
+Write your scripts using the [`ph7.js`](/js) APIs.
+
+<!-- {"type": "html", "file": "examples/django_app/javascript/templates/script.py", "input_only": true} -->
 ```python
-from django import forms
+from ph7.js import alert, console, document, fetch, js_callable
 
-from ph7.html import body, div, form, html, title
 
+@js_callable
+async def fetchDog():
+    console.log("Fetching dog")
+    response = await fetch(
+        "https://dog.ceo/api/breeds/image/random",
+        {
+            "method": "GET",
+        },
+    )
+    data = await response.json()
+    console.log("Dog fetched")
+    document.getElementById("image").src = data.message
+```
 
-class UserForm(forms.Form):
-    """User form class."""
+<!-- end -->
 
-    name = forms.CharField(label="username")
-    email = forms.EmailField(label="email")
-    password = forms.CharField(label="password", widget=forms.PasswordInput())
+Use the function in the view
+
+<!-- {"type": "html", "file": "examples/django_app/javascript/templates/__init__.py", "input_only": true} -->
+```python
+from javascript.templates.script import fetchDog
+from javascript.templates.styles import image, main
 
+from ph7.context import ctx
+from ph7.html import body, button, div, head, html, img
+
+ctx.static.view(__name__)
 
 template = html(
-    title("Forms Example"),
+    head(
+        ctx.static.include,
+    ),
     body(
         div(
-            form(
-                UserForm(),
+            img(
+                src="#",
+                id="image",
+                alt="Click to fetch dog",
+                class_name=image,
+            ),
+            button(
+                "Click to fetch a dog",
+                handlers={
+                    "onclick": fetchDog(),
+                },
             ),
+            class_name=main,
         )
     ),
 )
+
+
+if __name__ == "__main__":
+    print(template.render({"_view": __name__}))
 ```
 
 <!-- end -->
 
+This is what the rendered view looks like
+
 ```html
 <html>
-    <head>
-        <title>Forms example</title>
-    </head>
-    <body>
-        <div>
-            <form>
-                <label for="id_name">username:</label>
-                <input type="text" name="name" required="" id="id_name">
-                <label for="id_email">email:</label>
-                <input type="email" name="email" maxlength="320" required="" id="id_email">
-                <label for="id_password">password:</label>
-                <input type="password" name="password" required="" id="id_password">
-            </form>
-        </div>
-    </body>
+  <head>
+    <link
+      href="/static/css/javascript_templates_styles.css"
+      rel="stylesheet"
+      id="css.javascript.templates.styles"
+    />
+    <script
+      src="/static/js/javascript_templates_script.js"
+      id="js.javascript.templates.script"
+    ></script>
+  </head>
+  <body>
+    <div class="main">
+      <img src="#" alt="Click to fetch dog" id="image" class="image" /><button
+        onclick="fetchDog()"
+      >
+        Click to fetch a dog
+      </button>
+    </div>
+  </body>
 </html>
 ```
+
+And this is what the rendered script looks like
+
+```js
+async function fetchDog() {
+  console.log("Fetching dog");
+  let response = await fetch("https://dog.ceo/api/breeds/image/random", {
+    method: "GET",
+  });
+  let data = await response.json();
+  console.log("Dog fetched");
+  document.getElementById("image").src = data.message;
+}
+```
diff --git a/docs/html.md b/docs/html.md
@@ -338,9 +338,9 @@ print(f"Third render: {time.perf_counter() - tick}")
 ```
 
 ```stdout
-First render: 6.573292917
-Second render: 0.5675741249999993
-Third render: 0.40496804200000014
+First render: 6.121663833
+Second render: 0.3590905419999997
+Third render: 0.3504045420000006
 ```
 <!-- end -->
 

diff --git a/docs/index.md b/docs/index.md
@@ -1,3 +1,14 @@
+## Why PH7?
+
+* Native to python
+* More code modularity
+* Easy to write reusable components
+* Editor support
+    * Syntax highlighting
+    *  Code navvigation tools
+    *  Auto-completion
+*  Type safety using MyPy
+
 ## Install
 ```
 pip3 install ph7

diff --git a/examples/css_example.py b/examples/css_example.py
@@ -0,0 +1,12 @@
+from ph7.css import CSSObject
+
+
+class flex_center(CSSObject):
+    """Flex center"""
+
+    display = "flex"
+    align_items = "center"
+    justify_content = "center"
+
+
+print(flex_center())