Skip to content

Commit

Permalink
- created local copy of RSS news feed, because direct download is blo…
Browse files Browse the repository at this point in the history 
…cked by CORS

- updated http-server
  • Loading branch information
@genemars
genemars committed Feb 19, 2022
1 parent b32a6dc commit fde95b6
Show file tree
Hide file tree
Showing 17 changed files with 13,058 additions and 160 deletions.
75 changes: 50 additions & 25 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@

A Progressive Web App template with a responsive layout and mobile app look & feel.

This template is built with just HTML, JavaScript and CSS so that it can be eventually integrated with your favourite development environment and build tools.
This template is built with just HTML, JavaScript and CSS so that it can be eventually integrated with your favourite
development environment and build tools.


## Features
Expand All @@ -25,23 +26,27 @@ https://zuixjs.github.io/zuix-html-pwa

# How to use this template

The **./source** folder contains the *development* version of the website, while the **./docs** folder the *production* bundled version.
The **./source** folder contains the *development* version of the website, while the **./docs** folder the *production*
bundled version.

## Basic usage

If you have *Node.js* installed, for a quick setup you can use the integrated web server which will serve files from the *./source* folder.
If you have *Node.js* installed, for a quick setup you can use the integrated web server which will serve files from the
*./source* folder.
Install the development dependencies with `npm install` and then start the web server:

```
npm start
```

If you don't want to use the integrated web server, you can setup any other web server by creating a new host with the root path pointing to the *./source* folder.
If you don't want to use the integrated web server, you can setup any other web server by creating a new host with the
root path pointing to the *./source* folder.


## Site structure in brief

The main file is the `index.html`. This file includes some layout bits that are located in the `layout/` folder and the main application pages that are located in the `pages/` folder.
The main file is the `index.html`. This file includes some layout bits that are located in the `layout/` folder and the
main application pages that are located in the `pages/` folder.

```
./source/
Expand Down Expand Up @@ -72,13 +77,17 @@ The main file is the `index.html`. This file includes some layout bits that are
main_menu.html
```

A simple page is defined by the `.css` and `.html` files. A page might also require some bits of *JavaScript* in which case also a `.js` file with the same base name is present.
A simple page is defined by the `.css` and `.html` files. A page might also require some bits of *JavaScript* in which
case also a `.js` file with the same base name is present.

A page might also include some other *local* bits that are placed in a subfolder with the same base name of the page like shown in the above structure for the `home` page.
A page might also include some other *local* bits that are placed in a subfolder with the same base name of the page
like shown in the above structure for the `home` page.

The `shared/` folder contains indeed bits that are *shared* across the whole application and that are usually referenced by different pages.
The `shared/` folder contains indeed bits that are *shared* across the whole application and that are usually referenced
by different pages.

As you can see in the `index.html` file those pages and layout bits are loaded using some special tag attributes that are `data-ui-include` (to load simple content pages) and `data-ui-load` to load pages or components that also have a JavaScript controller.
As you can see in the `index.html` file those pages and layout bits are loaded using some special tag attributes that are
`data-ui-include` (to load simple content pages) and `data-ui-load` to load pages or components that also have a JavaScript controller.

**index.html** (main body)
```html
Expand Down Expand Up @@ -114,7 +123,8 @@ As you can see in the `index.html` file those pages and layout bits are loaded u
</div>
```

For a deeper insight on using these special attributes for component-based developemnt with **zUIx.js** see related link at the bottom of this page.
For a deeper insight on using these special attributes for component-based developemnt with **zUIx.js** see related link
at the bottom of this page.

### The news list

Expand All @@ -135,12 +145,15 @@ In order to display the list of news articles, the `pages/home` is using the `pa
...
```

Once the `items_list` component is loaded it will read the attribute `data-o-rss` of the element and download the RSS feed specified by it. Then it will parse the RSS feed and render it to the wrapping element.
This component is just an example and you can modify and adapt it to work with any data source or it can be replace with a server-side rendering approach.
Once the `items_list` component is loaded it will read the attribute `data-o-rss` of the element and download the RSS
feed specified by it. Then it will parse the RSS feed and render it to the wrapping element.
This component is just an example and you can modify and adapt it to work with any data source or it can be replace with
a server-side rendering approach.

### About the @lib prefix

The special *@lib* prefix is used with the `data-ui-include` and `data-ui-load` attribute to load components from a shared location that by default will point to the [zKit](https://zuixjs.github.io/zkit/) components library.
The special *@lib* prefix is used with the `data-ui-include` and `data-ui-load` attribute to load components from a
shared location that by default will point to the [zKit](https://zuixjs.github.io/zkit/) components library.
This path is resolved to `https://zuixjs.github.io/zkit/lib/` but can also be customized to point to a different location:

```javascript
Expand All @@ -153,19 +166,24 @@ You can so create your own shared component library to use across all of your we

### Further implementation details

If you have more questions about how to use this template do not esitate to [file an issue](https://github.com/zuixjs/zuix-html-pwa/issues).
If you have more questions about how to use this template, do not hesitate to [file an issue](https://github.com/zuixjs/zuix-html-pwa/issues).


## Service Worker and Offline mode

A service worker is also included with this template. This is a script (`sw.js`) that runs in the background as a seprate thread from the main page and takes care of providing caching of most resources with a fallback mechanism in presence of network errors.
This makes the application to launch even if there's no network connection, like with a real mobile app. It also provide a configurable `404.html` *"not found"* page and `offline.html` page.
When publishing a new version of the application the *version number* found at the top of the `sw.js` file **must be increased** in order to clean the cache and correctly update the application files.
A service worker is also included with this template. This is a script (`sw.js`) that runs in the background as a separate
thread from the main page and takes care of providing caching of most resources with a fallback mechanism in presence of
network errors.
This makes the application to launch even if there's no network connection, like with a real mobile app. It also provides
a configurable `404.html` *"not found"* page and `offline.html` page.
When publishing a new version of the application the *version number* found at the top of the `sw.js` file **must be increased**
in order to clean the cache and correctly update the application files.


## Debugging

To enable verbose debugging information in the browser console, comment out the last line in the `index.js` file as shown below:
To enable verbose debugging information in the browser console, comment out the last line in the `index.js` file as
shown below:

``` javascript
// Turn off debug output
Expand All @@ -177,21 +195,24 @@ To enable verbose debugging information in the browser console, comment out the

Bundling is the process of collecting all resources used in a page and then compiling them into a single and optimized file.

This will drastically narrow down the number of network requests the browser will make to complete the page loading, thus resulting in a faster startup.
This will drastically narrow down the number of network requests the browser will make to complete the page loading,
thus resulting in a faster startup.

There are actually two way of doing this:

- **In-Browser** bundler:
this method does not require any build tool nor plugins, it just works in the browser as-is.

- **Web-Starter** bundler:
is the [zuix-web-starter](https://github.com/zuixjs/zuix-web-starter) bare template, with a bunch of extra features and enhancements. It requires *Node.js* to be installed.
is the [zuix-web-starter](https://github.com/zuixjs/zuix-web-starter) bare template, with a bunch of extra features and
enhancements. It requires *Node.js* to be installed.

This template is already configured for **in-browser** bundling.

### In-Browser bundling

When the website is ready for production you can decide to bundle it in order to gain better performances. All of its components and resources will be crunched into a single file and loaded from memory rather than from network/localhost.
When the website is ready for production you can decide to bundle it in order to gain better performances. All of its
components and resources will be crunched into a single file and loaded from memory rather than from network/localhost.

#### Step by step guide

Expand All @@ -203,11 +224,13 @@ zuix.saveBundle()

This will create and save the **app.bundle.js** file to the *Downloads* folder.

Copy all files from the *source* folder to the **production** folder (*./docs*) with the exception of *./components*, *./controllers*, *./pages*, *./layout* and *./index.css*.
Copy all files from the *source* folder to the **production** folder (*./docs*) with the exception of *./components*,
*./controllers*, *./pages*, *./layout* and *./index.css*.

These folders contain *zuix* components and pages that are already packed in the *app.bundle.js* file.

Copy *app.bundle.js* to the *production* folder. Edit the `index.html` file in the *production* folder and in the `head` section replace the `js/zuix-bundler.min.js` script import with `app.bundle.js`.
Copy *app.bundle.js* to the *production* folder. Edit the `index.html` file in the *production* folder and in the `head`
section replace the `js/zuix-bundler.min.js` script import with `app.bundle.js`.

```html
<script src="js/zuix.min.js"></script>
Expand All @@ -231,7 +254,8 @@ zuix.componentize()
zuix.saveBundle()
```

Also external JavaScript libraries and CSS files can be included in the page bundle. In order to achieve this, remove the `<script src="..."></script>` or `<link rel="stylesheet">` and instead use the method `zuix.using(...)` to load the script/css.
Also external JavaScript libraries and CSS files can be included in the page bundle. In order to achieve this, remove
the `<script src="..."></script>` or `<link rel="stylesheet">` and instead use the method `zuix.using(...)` to load the script/css.

```javascript
// Loading a .css style
Expand All @@ -246,7 +270,8 @@ zuix.using('script', momentJs, function(res, scriptObject){
});
```

Place the *using* commands preferably at the top of `index.js`. You can remove from the *production* folder all files imported with the *using* command.
Place the *using* commands preferably at the top of `index.js`. You can remove from the *production* folder all files
imported with the *using* command.

# Further reading

Expand Down
Loading

0 comments on commit fde95b6

Please sign in to comment.