Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@pranavr2003
pranavr2003 authored Jul 19, 2021
1 parent 87d6fc1 commit 528201a
Showing 1 changed file with 136 additions and 122 deletions.
258 changes: 136 additions & 122 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,168 +6,181 @@

![GitHub](https://img.shields.io/github/license/BrainStormYourWayIn/sierra?color=blue)

Sierra is a Python native engine for web development, which makes templating for the backend easy, as well as have full control on your frontend. You can now develop your web application purely in Python, taking full advantage of its powerful functionalities with simple and elegant syntax.
Sierra is a Python library to write HTML and CSS in pure Python using the DOM API in a simple yet elegant manner. Take advantage of Python's powerful
functionalities with ease. Loops, variables, functions, libraries - you name it, you have it.

This was in part inspired by [Dominate](https://github.com/Knio/dominate), but has support for CSS styling attributes, better syntax, more use cases and many more functionalities
Here are a few advantages of using Sierra over other Python libraries that use the DOM API:

It can be used standalone in developing web applications
- Out-of-the-box support for all CSS styling attributes for all tags
- Display a table by simply putting in a CSV file
- Create your own tag functions with absolute ease using `@tag` and `@CmTag`. You can decide their behavior and use them within content-managers too
- Improvement in the arrangement look of the code and intelligent handling of tags with
`autoPrettify()` - Powered by bs4 and a feature like no other

You can also use this as an alternative to jinja or Django's templating or any other templating engine, or even use it along with one

It's got features like displaying a table on the web application by loading in a .csv file, adding a bulleted list (ol/ul) by just passing in a list, automatic support for CSS styling arguments and more! You can use for loops, variables, functions - you name it, you have it, with Sierra. Improvement in the overall look of the code and intelligent handling of tags with `autoPrettify()`, a feature like no other. Harness the power of Python for your web applications!
You may also use this as a templating engine, although jinja and Django's templating engine is strongly recommended over this

________________________________

## Documentation

- **Check out the [documentation of Sierra](https://brainstormyourwayin.github.io/sierra.github.io/)**
- **Check out a [few examples](https://github.com/BrainStormYourWayIn/sierra_examples/) of its use**

> The examples mentioned above is a simple bare-boned book search engine created with requests, bs4, Flask and Sierra; and the documentation of Sierra, which was written with Sierra standalone
________________________________

This is intended for used in developing less resource-heavy web applications (since this hasn't been tested with any resource-heavy ones) which involve a good amount of Python code, and if you want to work exclusively on Python without using another templating engine (jinja, Django's templating). Although you may use this with them if the use case suits you.

________________________________
**Have a look at `src/sierra/custom_tags.py` and `release_prots.py` for a sneak-peek on the next release updates. We got some things going on there!**
________________________________

**Installation and Upgrade**

## Example

Using this with Flask makes life easier if you're developing web applications with just HTML and CSS. Adding JS with manual functions will be supported by Sierra in the coming release(s)

Here's a little example for this:

pip install sierra

pip install --upgrade sierra

Starting off is pretty simple and straightforward:
```python
from flask import Flask, render_template
from sierra import *

title('Hello World!')
```

The `title()` function at the start is mandatory, since it commences the HTML and the CSS file, which is created in the working directory upon execution on the code.

app = Flask(__name__)

def the_template():
title('Some title', templating=True) # Set templating to True if you're using Flask
head('Just a heads up', 'h2')
openBody()

def adding_table():

the_template()
with div(None, attr="id='div_id'"):

with startTable() as st: # Creating a table within the <div> tag
You can create custom tag functions with @tag and @CmTag with just three lines of code. Say you want to create a function for &lt;meta&gt;:
```python
@tag
def meta(**kwargs):
pass

st.getTable('path/to/file.csv')
st.css(font_family="Arial, Helvetica, sans-serif", border="1px solid #d1d5e8", padding='8px', width='20%')


autoPrettify()
write_to_template('index1.html')

def pre_and_unordered_list():

the_template()
with div(div_class='description_list'):

with open_tag('pre') as pr:
writeWA("Some text within the <pre> tag")
pr.css(background_color="#e1e8e3")

with section(sec_class='unordered_list') as s: # Creating section inside div
ul_list = ['This', 'is', 'an', 'unordered', 'list']
with bullets(ul=True, points=ul_list):
pass

autoPrettify()
write_to_template('index2.html')

@app.route("/adding_table")
def show_adding_table():
adding_table()
return render_template('index1.html')

@app.route("/pre_and_unordered_list")
def show_pre_and_unordered_list():
pre_and_unordered_list()
return render_template('index2.html')

if __name__ == '__main__':
app.run()
# Using them

meta(name="description", content="This is some description")
meta(name="viewport", content="width=device-width", initial_scale=1.0)
```

First, the directory structure needs to get sorted before running this. Run the code outside of `templates/`.
Underscores are used for hyphens (same applies to CSS) and Python-conficting arguments are prefixed with a double underscore.

Here with `write_to_template()`, you can name your HTML file and call the function which takes only that argument to write the file into the `templates/` folder. `style.css` is automatically put into `static/` when this function is called.
Using argument `text` inside of a function defined in `@tag` will create a tag that opens, enters text, and closes. Something like this:
```python
@tag
def script(**kwargs):
pass
script(__async="", src="some_src", text="some_text")
```
Is the equivalent of:
```html
<script async="" src="some_src">some_text</script>
```
Want to add some JS? Simple enough. Just create a function for the &lt;script&gt; tag with a context manager behavior using `@CmTag` and you're golden.
```python
@CmTag
def script(**kwargs):
pass

In `title()`, set the argument `templating` to True, if Sierra is being used to template with Flask
# Here I'll be replicating the script needed to add Google Analytics to a webpage

Of course, you can also define the functions in separate files and import it.
with script(__aync="", src="https://www.googletagmanager.com/gtag/js?id=UA—XXXXXXXX-X"):
pass

with script():

writeWA('''
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'UA—XXXXXXXX-X');
''')
```
This is the equivalent of:
```html
<script async src="https://www.googletagmanager.com/gtag/js?id=UA—XXXXXXXX-X"></script>

Sierra can also be used standalone without Flask, like this:
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'UA—XXXXXXXX-X');
</script>
```
`writeWA()` writes text entered into it into the HTML file as it is.

You can add fonts using `addFont()`
```python
addFont("https://fonts.googleapis.com/css2?family=Roboto&display=swap")
```
Once things at the `<head>` of the HTML are settled (CSS is automatically linked), begin the body of the HTML with
```python
from sierra import *

title('The title goes here')
head('Sierra!', type='h2', color="#0388fc")
openBody()

with open_tag('newTag'):

with div('someClass') as d:
p('Some text within the div')
d.css(background_color='rgb(211, 111, 121)') # Adding CSS to the div

with section('anotherClass', "id='some_id'"): # Creating section within the div within 'newTag'
with startTable() as st:
st.getTable(/path/to/file.csv, attr="id='table_id'")

with cTags('#table_id') as t:
t.css(font_family="Arial, Helvetica, sans-serif", border="1px solid #d1d5e8", padding='8px', width='20%')

p("This is a paragrah within a section, which is within a div tag and comes afer the table")

with image(src='sierra.jpg'):
i.show() # Displaying an image
i.css(opacity=1.2) # Adding CSS to it

p("This is a paragraph that doesn't come under any div or a section, but comes under <newTag>. Simple stuff, really!")

autoPrettify()
# You can add any number of styling arguments to the body within openBody()
openBody(background_color='yellowgreen', opacity='0.9')
```
You can create `div` and `section` tags this way:
```python
with div(__class="some_class") as d:
p('This is a paragraph!')
d.css(background_color="#5886d1")
```
Let's break this down but-by-bit:
First, we start a `div` with a context manager behavior and give it an attribute `__class`, which is essentially the tag attribute `class` (remember Python-conflicting) arguments are prefixed by a double underscore.

### See the [documentation](https://brainstormyourwayin.github.io/sierra.github.io/) for more
`p()` is a function, as the name suggests, to add a `<p>` tag. You can give the tag attributes with `**kwargs`, if you like.
`p('Hello World!', __class='p_class')` is the same as `<p class="p_class">Hello World!</p>`

________________________________
After the paragraph, there's a `d.css()`. This adds CSS to the `class` mentioned within `div()`. If a `class` is mentioned, CSS is added to that class as the first priority. If an `id` is mentioned, CSS is added to that `id` as a second priority. If none of both are mentioned, CSS is just added to `div`.

## Installation
The behavior of `div` shown above also applies to `section`.

To download the library:
You can open a new tag with `Tag()`
```python
with Tag('some_tag', id='some_id') as t:
p('A paragraph in <some_tag>')
t.css(color='blue')
```
Although here, `.css()` behaves differently. It is independent of tag attributes, meaning CSS is added directly to the tag mentioned, which is `some_tag`

pip install sierra
To add CSS to a specific attribute in the tag, use `writeCSS()`
```python
writeCSS(tag_name, **kwargs)

________________________________
writeCSS("#some_id", color='blue')
```
This adds CSS to the `some_id`.

## Upgrade
You can add a table to the HTML page by inputting in a CSV file this way:
```python
with Table() as t:
t.get_table("path/to/file.csv") # Add attributes with **kwargs here
t.css(border="1px solid black") # Use writeCSS to add CSS to a specific attribute
```
There are MANY more functionalities to Sierra that you can see from the [documentation](https://brainstormyourwayin.github.io/sierra.github.io/)

To upgrade the library:
At the end of all development with Sierra, use
```python
autoPrettify()
```
It takes in no arguments, but provides SO much to the code.

pip install --upgrade sierra
Try running this WITHOUT `autoPrettify()` at first and see `index.html`, and then WITH it, and see `index.html` again:

________________________________
```python
title('Some title')
head('Some header', 'h2')

### Upcoming (in order of priority):
openBody()

- Enable auto-introduction of custom tags tags like `span`, `label`, `input` or anything, with decorators (See `release_prots.py`)
- In-memory storage for the HTML and CSS file (See `release_prots.py`)
- Deprecate cTags() and just introduce a new function called css(), since adding CSS with a class is longer than simply doing css('.some_class', color='blue', font_size='20px')
- Deprecate the attr argument and instead use **kwargs to add tag attributes
- Add an option for in-memory storage, see release_prots.py
- Use `kwargs` to add tag attributes
- Change startTable and createTable to start_table and create_table
with div(__class='some_class') as d:
p('Some text that falls inside the division')
d.css(background_color='black')

with section(id='some_id') as sec:
p('Some text within a section within a div')
sec.css(background_color='red')

with bullets(ul=True, points=['foo', 'bar', 'baz']):
pass

writeCSS('p', color='white')

**See `release_prots.py`**
autoPrettify() # --> Try without this and see index.html, then with this and have a look at index.html again
```

________________________________

Expand All @@ -179,6 +192,7 @@ Email: [email protected]

________________________________

**Open with GitPod**

[![GitPod](https://www.gitpod.io/svg/media-kit/logo-dark-theme.svg)](https://gitpod.io/#https://github.com/BrainStormYourWayIn/sierra/)

Expand Down

0 comments on commit 528201a

Please sign in to comment.