Browse Source

Create docs

master
Skylar Ittner 1 year ago
commit
b6b2ad9ab4
7 changed files with 716 additions and 0 deletions
  1. 1
    0
      .gitignore
  2. 75
    0
      docs/System Requirements.md
  3. 380
    0
      docs/Theme Development.md
  4. 117
    0
      docs/images/docs-icon.svg
  5. 104
    0
      docs/images/logo.svg
  6. 23
    0
      docs/index.md
  7. 16
    0
      mkdocs.yml

+ 1
- 0
.gitignore View File

@@ -0,0 +1 @@
site/

+ 75
- 0
docs/System Requirements.md View File

@@ -0,0 +1,75 @@
# System Requirements

SiteWriter (and the other Business Apps) are tested and officially supported on the following configurations. Other systems may be supported at our discretion, possibly with an additional support fee. The business apps should work on any sane Linux/PHP/MySQL based web server, even if it is not within the requirements shown here.

## Server

### Minimum Hardware

The Business Apps are very lightweight on server resources. The minimum supported hardware is a $35 Rasperry Pi 3 (1.2 GHz quad-core ARM CPU, 1GB RAM, 100Mbps Ethernet). Cloud VPS servers with as little as 512 MB RAM are fine too.

### Software and Operating System

* Server Operating System
* Ubuntu
* Debian
* PHP
* 7.0
* 7.1
* 7.2
* Database
* MySQL 5.7+
* MariaDB 10.0+
* Web Server
* Apache 2.4

### Recommended Software
For best performance, security, and ease of administration, we recommend installing the following on your server:

* Google's ModPageSpeed Apache module (on-the-fly caching and bandwidth optimization)
* PHP's opcache (cached compiled PHP code for faster execution)
* Fail2ban (if using SSH or other remote administration methods)
* PHPMyAdmin (web-based MySQL/MariaDB server administration)
* LetsEncrypt (automatic free SSL encryption setup)

## Client

The Business Apps are web-based and built with modern technologies. This means any machine capable of running a standards-compliant, modern, up-to-date web browser will run the Business Apps just fine.

### Officially Supported Operating Systems
Note: This list is incomplete, as any OS capable of running one of the browsers from the list below will suffice.

* Linux
* Ubuntu Linux 16.04, 18.04, and supported non-LTS releases
* Ubuntu derivatives (such as Linux Mint) based on a supported Ubuntu release
* Debian 8 or 9
* Android
* 5.0+ with Chrome, or
* Any supported by Firefox, or
* Any supported by the Business Apps for Mobile client

### Supported Operating Systems
Any other operating system running a supported browser is also supported, but we may not provide support for issues not directly related to the Business Apps.

### Supported Screen Resolutions
All screens with a viewport (the portion of the screen showing the app, in contrast to window borders, status bars, etc) having a resolution greater than 300x400 pixels will work, assuming use of a supported browser.

### Supported Web Browsers
* Mozilla Firefox (54+)
* Chrome/Chromium (latest and latest-1)
* Chrome WebView, AOSP WebView (Android 5.0+)

### Unsupported Web Browsers
While we do not support the following browsers, they will likely still work. You won't break anything by trying.

* Edge
* Safari
* Opera

### Known Incompatable Browsers
These browsers are known to lack support for CSS rules, JavaScript APIs, and other technology required to run the Business Apps.

* Opera Mini
* Internet Explorer

Recent versions of Internet Explorer should be able to view created websites with some minor changes.

+ 380
- 0
docs/Theme Development.md View File

@@ -0,0 +1,380 @@
# Theme Development

Themes are a collection of page templates, assets (CSS, JS, etc) and a metadata file. They should use responsive design and be easily edited and viewed. Providing a variety of color schemes is recommended for users to choose from when building their site.

## Folder Structure

This is the folder structure for a standard theme. The root folder shown below should be placed in `[sitewriter app]/public/themes`. **Bold** denotes a folder, *italic* denotes required.

* Theme Name
* _theme.json_
* contact.php
* _default.php_
* _404.php_
* ***colors***
* ***default***
* **green**
* **etc**

## Metadata File

The metadata file is required for SiteWriter to recognize the theme. It must be saved as `theme.json` in the root folder of the theme.

It contains the theme name, singlepage flag, list of page templates, and list of theme colors.

`singlepage` is a flag that tells SiteWriter if the theme is designed for a single-page website. If it is set to true, page creation will be disabled and the site will only have a single page.

`templates` is a list of page templates. A template with an ID of `default` is required. The template ID is the name of the template file without the .php extension. For example, SiteWriter loads `home.php` to show a page with the `home` template.

`colors` is a list of color schemes for the theme. The color ID is the name of the folder where the color-specific assets are stored. A color of `default` is required. If the chosen color is `green`, the color-specific assets should be placed in `colors/green` in the theme folder.

### Sample `theme.json`

```js
{
"name": "My Theme",
"singlepage": false,
"templates": {
"default": {
"title": "Default",
"description": "A regular page."
},
"home": {
"title": "Home",
"description": "A homepage."
},
"contact": {
"title": "Contact",
"description": "A contact page."
},
},
"colors": {
"default": {
"title": "Default",
"description": "Blue color theme"
},
"green": {
"title": "Green",
"description": "Green color theme"
}
}
}

```

## Templates

### `default.php`

`default.php` is the default template file for a normal page in your theme. It is a standard PHP script containing HTML markup. It should never be loaded directly by a web browser, so you can safely assume theme functions and other SiteWriter theme utilities to be present.

### `404.php`

As the name implies, this template is loaded to handle 404 errors. It is not user-selectable as a page template. It should not contain any user-editable fields, as there is currently no way for a user to edit site error pages.

### `contact.php`

It is highly recommended to have a contact form template included in your theme. It should contain a standard form that POSTs to `contact.php` with the fields `name`, `email`, and `message`.

## Template Requirements and Considerations

Do not use the optional `<html>`, `<head>`, and `<body>` tags for your template HTML. The editor relies on being able to append code to the document and have it still work normally.

Do include FontAwesome 5 in your theme. The SiteWriter editor allows the user to pick icons from the FontAwesome Free icon set to enhance their content.

Do include company info (business name, phone number, address, and email) and social media links (Facebook, Twitter, YouTube, Mastodon, etc) in the theme. These can be setup in the sitewide settings, and users will expect themes to make use of this information.

Do include `<?php get_header(); ?>` and `<?php get_footer(); ?>` snippets in your templates. They are used to inject additional content into the template, such as third-party analytics code.

Do copy code from the Bootstrap theme included with SiteWriter.

## Common Component Names

To make theme transitions as seamless as possible, try to use the same component names as other themes for equivalent components.

* Page subtitle: `lead`, plain text
* Page content: `content`, rich text
* Page banner (not page title): `banner-title`, plain text
* Content cards: `cardrow-$i`, rich text (where $i is a number between 1 and 3)
* Action buttons above the fold: `banner-btn-$i`, complex component with icon, link, and text (where $i is 1 or 2)
* Contact form submit button: `submit-btn`, complex component with icon and text

Consult the included Bootstrap and Verti themes for example usage of these common components.

## Example Template

Below is a minimal functional `default` template that fulfills the above requirements.

```html
<!DOCTYPE html>
<meta charset=`utf-8`>
<title><?php get_site_name(); ?></title>
<script defer src="<?php get_theme_url(); ?>/fontawesome-all.min.js"></script>
<?php get_header(); ?>
<!-- Navbar -->
<ul>
<?php get_navigation(); ?>
</ul>
<h1><?php get_page_title(); ?></h1>
<h2>
<div class="sw-text" data-component="lead">
<?php get_component("lead"); ?>
</div>
</h2>
<div class="sw-editable" data-component="content">
<?php get_page_content(); ?>
</div>
<footer>
<!-- Social Media -->
<ul>
<?php
$social = get_socialmedia_urls();
foreach ($social as $s) {
?>
<a class="btn btn-outline-primary m-1" href="<?php echo $s['url']; ?>">
<i class="<?php echo $s['icon']; ?> fa-fw"></i>
<span class="sr-only"><?php echo $s['name']; ?></span>
</a>
<?php
}
?>
</ul>
</footer>
```

## Code Snippets

### Plain Text Component

```html
<p class="sw-text" data-component="lead">
<?php get_component("lead"); ?>
</p>
```

### HTML Component

```html
<div class="sw-editable" data-component="component-name">
<?php get_component("component-name"); ?>
</div>
```

### Complex Component

```html
<?php
if (!is_complex_empty("banner-btn-2")) {
$btn = get_complex_component("banner-btn-2", null, ['icon', 'image', 'link', 'text']);
$icon = $btn['icon'];
$image = $btn['image'];
$link = $btn['link'];
$text = $btn['text'];
?>
<a href="<?php get_url_or_slug($link); ?>" class="sw-complex" data-json="<?php echo get_escaped_json($btn); ?>" data-component="banner-btn-2">
<i class="<?php echo $icon; ?>"></i>
<?php echo $text; ?>
<img src="<?php echo $image; ?>" />
</a>
<?php } ?>
```

## Theme Functions

### `get_site_name($echo = true)`

Get the name of the website.

* **Parameters:** `$echo` — `boolean` — default true
* **Returns:** `string` —

### `get_site_url($echo = true)`

Get the URL of the website.

* **Parameters:** `$echo` — `boolean` — default true
* **Returns:** `string` —

### `get_page_title($echo = true)`

Get the page title.

* **Parameters:** `$echo` — `boolean` — default true
* **Returns:** `string` —

### `get_page_clean_title($echo = true)`

Get the page title stripped of any HTML.

* **Parameters:** `$echo` — `boolean` — default true
* **Returns:** `string` —

### `get_page_slug($echo = true)`

Get the page slug for the current page.

* **Parameters:** `$echo` — `boolean` — default true
* **Returns:** `string` —

### `get_page_clean_url($echo = true, $slug = null)`

Get a valid minimal URL for a page.

* **Parameters:**
* `$echo` — `boolean` — default true
* `$slug` — `string` — page slug, or null for current
* **Returns:** `string` —

### `get_page_url($echo = true, $slug = null)`

Get a valid URL for a page.

* **Parameters:**
* `$echo` — `boolean` — default true
* `$slug` — `string` — page slug, or null for current
* **Returns:** `string` —

### `get_component($name, $context = null, $echo = true)`

Echoes or returns the content of a component.

* **Parameters:**
* `$name` — `string` — component name
* `$context` — `string` — page slug, or null for current
* `$echo` — `boolean` — default true
* **Returns:** `string` —

### `is_component_empty($name, $context = null)`

Check if a component is empty of content.

* **Parameters:**
* `$name` — `string` — component name
* `$context` — `string` — page slug, or null for current
* **Returns:** `boolean` —

### `get_complex_component($name, $context = null, $include = [])`

Return the data for a complex component (icon, link, text, image, etc)

* **Parameters:**
* `$name` — `string` — component name
* `$context` — `string` — page slug, or null for current
* `$include` — `array` — list of properties to include in the output
* **Returns:** `array` —

### `is_complex_empty($name, $context = null)`

Check if the specified complex component is empty.

* **Parameters:**
* `$name` — `string` —
* `$context` — `string` — page slug
* **Returns:** `boolean` —

### `get_escaped_json($json, $echo = true)`

Convert a variable into encoded JSON for safe inclusion in an element property.

* **Parameters:**
* `$json` — or array to convert to JSON
* `$echo` — `boolean` — default true
* **Returns:** `string` —

### `get_url_or_slug($str, $echo = true)`

Detects if a string is a URL or a page slug, and returns something usable for href

* **Parameters:**
* `$str` — `string` —
* `$echo` — `boolean` —
* **Returns:** `string` —

### `get_page_content($slug = null)`

Shortcut for get_component("content").

* **Parameters:** `$slug` — `string` — Get the content for the passed page instead of the current.

### `get_header()`

Echoes invisible page header content.

### `get_footer()`

Echoes invisible page footer content.

### `get_setting($key, $echo = false)`

Return or echo the value of the given site setting key, or an empty string if unset.

* **Parameters:**
* `$key` — `string` —
* `$echo` — `boolean` — default false
* **Returns:** `string` —

### `get_theme_url($echo = true)`

Get the URL path for the theme folder, without trailing slash.

* **Parameters:** `$echo` — `boolean` — default true
* **Returns:** `string` —

### `get_theme_color_url($echo = true)`

Get the URL base for the selected theme color asset folder, without trailing slash.

* **Parameters:** `$echo` — `boolean` — default true
* **Returns:** `string` —

### `get_navigation($currentpage = null, $classPrefix = "", $liclass = "", $currentclass = "current", $linkclass = "", $currentlinkclass = "active")`

Get the page navigation as a string containing a series of `<li><a></a></li>` elements.

**Format:**
Current page:
```html
<li class="$classPrefix$slug $liclass $currentclass">
<a class="$linkclass $currentlinkclass" href="url">
Link Text
</a>
</li>
```
Other pages:
```html
<li class="$classPrefix$slug $liclass">
<a class="$linkclass" href="url">
Link Text
</a>
</li>
```

* **Parameters:**
* `$currentpage` — `string` — The page slug to use for context, or null for current.
* `$classPrefix` — `string` —
* `$liclass` — `string` —
* `$currentclass` — `string` — default "current"
* `$linkclass` — `string` —
* `$currentlinkclass` — `string` — default "active"

### `output_conditional($content, $var)`

Replace "[[VAR]]" with the contents of $var and echo $content, but only if $var isn't empty.

* **Parameters:**
* `$content` — `string` —
* `$var` — `string` —

### `get_fontawesome_js($echo = true)`

Echos or returns a URL for the FontAwesome 5 JavaScript.

* **Parameters:** `$echo` — `boolean` — default true
* **Returns:** `string` —

### `get_socialmedia_urls()`

Returns an array of social media URLs, with FontAwesome icon classes and labels.

* **Returns:** `array` — `[["icon", "name", "url"]]`

+ 117
- 0
docs/images/docs-icon.svg View File

@@ -0,0 +1,117 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->

<svg
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
width="512"
height="512"
viewBox="0 0 511.99999 511.99999"
id="svg2"
version="1.1"
inkscape:version="0.91 r13725"
sodipodi:docname="docs-icon.svg"
inkscape:export-filename="/home/skylar/Documents/Assets/Graphics/docs-icon.png"
inkscape:export-xdpi="45"
inkscape:export-ydpi="45">
<defs
id="defs4" />
<sodipodi:namedview
id="base"
pagecolor="#ffffff"
bordercolor="#666666"
borderopacity="1.0"
inkscape:pageopacity="0.0"
inkscape:pageshadow="2"
inkscape:zoom="0.98994949"
inkscape:cx="52.220574"
inkscape:cy="225.3771"
inkscape:document-units="px"
inkscape:current-layer="layer1"
showgrid="false"
units="px"
inkscape:window-width="1920"
inkscape:window-height="1023"
inkscape:window-x="107"
inkscape:window-y="1024"
inkscape:window-maximized="1" />
<metadata
id="metadata7">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
<dc:title />
</cc:Work>
</rdf:RDF>
</metadata>
<g
inkscape:label="Layer 1"
inkscape:groupmode="layer"
id="layer1"
transform="translate(0,-540.36219)">
<rect
y="593.73596"
x="56"
height="50"
width="400"
id="rect4187"
style="fill:#00b0ff;fill-opacity:1;stroke:none;stroke-width:5;stroke-miterlimit:4;stroke-dasharray:5, 5;stroke-dashoffset:0;stroke-opacity:1" />
<rect
style="fill:#9e9e9e;fill-opacity:1;stroke:none;stroke-width:5;stroke-miterlimit:4;stroke-dasharray:5, 5;stroke-dashoffset:0;stroke-opacity:1"
id="rect4150"
width="380"
height="50"
x="76"
y="683.25037" />
<rect
style="fill:#9e9e9e;fill-opacity:1;stroke:none;stroke-width:5;stroke-miterlimit:4;stroke-dasharray:5, 5;stroke-dashoffset:0;stroke-opacity:1"
id="rect4154"
width="380"
height="50"
x="76"
y="953.25037" />
<g
id="g4162"
style="fill:#bdbdbd">
<rect
style="fill:#bdbdbd;fill-opacity:1;stroke:none;stroke-width:5;stroke-miterlimit:4;stroke-dasharray:5, 5;stroke-dashoffset:0;stroke-opacity:1"
id="rect4148"
width="320"
height="50"
x="136"
y="773.25037" />
<circle
r="12.5"
cy="798.25037"
cx="101.19038"
id="path4160"
style="fill:#bdbdbd;fill-opacity:1;stroke:none;stroke-width:5;stroke-miterlimit:4;stroke-dasharray:5, 5;stroke-dashoffset:0;stroke-opacity:1" />
</g>
<g
transform="translate(40,90.000002)"
id="g4162-3"
style="fill:#bdbdbd">
<rect
style="fill:#bdbdbd;fill-opacity:1;stroke:none;stroke-width:5;stroke-miterlimit:4;stroke-dasharray:5, 5;stroke-dashoffset:0;stroke-opacity:1"
id="rect4148-6"
width="280"
height="50"
x="136"
y="773.25037" />
<circle
r="12.5"
cy="798.25037"
cx="101.19038"
id="path4160-7"
style="fill:#bdbdbd;fill-opacity:1;stroke:none;stroke-width:5;stroke-miterlimit:4;stroke-dasharray:5, 5;stroke-dashoffset:0;stroke-opacity:1" />
</g>
</g>
</svg>

+ 104
- 0
docs/images/logo.svg View File

@@ -0,0 +1,104 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
width="512"
height="512"
viewBox="0 0 511.99999 511.99999"
id="svg2"
version="1.1"
inkscape:version="0.91 r13725"
sodipodi:docname="logo.svg"
inkscape:export-filename="/home/skylar/Documents/Projects/Assets/SiteWriter/logo_512.png"
inkscape:export-xdpi="90"
inkscape:export-ydpi="90">
<sodipodi:namedview
pagecolor="#ffffff"
bordercolor="#666666"
borderopacity="1"
objecttolerance="10"
gridtolerance="10"
guidetolerance="10"
inkscape:pageopacity="0"
inkscape:pageshadow="2"
inkscape:window-width="1440"
inkscape:window-height="842"
id="namedview14"
showgrid="false"
inkscape:zoom="0.65186406"
inkscape:cx="-263.8452"
inkscape:cy="164.6375"
inkscape:window-x="1024"
inkscape:window-y="156"
inkscape:window-maximized="1"
inkscape:current-layer="svg2" />
<defs
id="defs4" />
<metadata
id="metadata7">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
<dc:title />
</cc:Work>
</rdf:RDF>
</metadata>
<rect
style="opacity:1;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:20;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:0.74509804"
id="rect4726-3"
width="512"
height="512"
x="0"
y="0"
rx="50"
ry="50" />
<path
id="rect4149"
d="m 151.84815,105.55999 c 0,0 208.08221,4e-4 208.08221,4e-4 8.87969,2e-5 17.47765,5.42434 19.32647,12.34724 0,0 68.50606,256.52161 68.50606,256.52161 4.65095,17.41553 -3.3789,32.03897 -18.20921,32.01073 0,0 -347.207046,-0.66126 -347.207046,-0.66126 -14.762494,-0.0281 -22.747362,-14.64569 -18.112131,-32.00219 0,0 68.337707,-255.88862 68.337707,-255.88862 1.84592,-6.91197 10.42061,-12.32792 19.27594,-12.32791 0,0 0,0 0,0"
style="opacity:1;fill:#03a9f4;fill-opacity:1;stroke:none;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
inkscape:connector-curvature="0" />
<g
transform="matrix(5.9992735,-11.249026,11.249026,5.999273,-1609.4403,-1737.4273)"
id="g2030"
style="display:inline;stroke-width:1.91200209" />
<rect
ry="11.220414"
rx="11.220414"
y="237.21503"
x="150.21944"
height="18.934093"
width="211.56111"
id="rect5279"
style="opacity:1;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:5;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
<rect
style="opacity:1;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:5;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
id="rect5281"
width="245.31049"
height="21.954561"
x="133.34476"
y="287.24475"
rx="13.010355"
ry="13.010355" />
<rect
style="opacity:1;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:5;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
id="rect5277"
width="188.55019"
height="16.874683"
x="161.7249"
y="189.24477"
rx="10"
ry="10" />
<path
style="opacity:1;fill:#3f51b5;fill-opacity:1;stroke:#ffffff;stroke-width:5;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
d="m 413.40083,100.4255 c -6.25994,-3.614167 -12.82305,-3.883777 -14.71576,-0.605517 L 267.15452,327.63761 c -0.1189,0.20593 -0.21483,0.42009 -0.29174,0.64289 -2.61136,2.10628 3.51508,29.26281 7.21558,31.3993 3.70042,2.13644 30.28348,-6.13458 30.80284,-9.44936 0.1545,-0.17801 0.28948,-0.3696 0.40838,-0.57554 L 436.82014,121.83727 c 1.8927,-3.27826 -1.62235,-8.82729 -7.88226,-12.44145 l -15.53706,-8.97032 z"
id="rect4549"
inkscape:connector-curvature="0" />
</svg>

+ 23
- 0
docs/index.md View File

@@ -0,0 +1,23 @@
# SiteWriter

SiteWriter is an easy-to-use website design system.

## Features

* __Simple Editor__
* Create awesome websites with zero coding or design experience.

* __Themes and Templates__
* Choose from a variety of website themes, color variations, and page templates.

* __Multi-site__
* Build and manage multiple websites at the same time

* __File Manager__
* Upload pictures and files and add them to your sites with a simple file browser tool.

* __Analytics__
* See visitor location, page views, and more with a built-in analytics dashboard.

* __Contact Forms__
* Simply create a page with a contact form template and start receiving and replying to messages from a dashboard.

+ 16
- 0
mkdocs.yml View File

@@ -0,0 +1,16 @@
site_name: SiteWriter Docs
theme:
name: 'material'
logo: 'images/logo.svg'
favicon: 'images/docs-icon.svg'
feature:
tabs: false
palette:
primary: 'light-blue'
accent: 'light-blue'
extra_javascript:
- track.js
site_author: Netsyms Technologies
repo_name: 'Business/SiteWriter'
repo_url: 'https://source.netsyms.com/Business/SiteWriter'
copyright: Copyright &copy; 2018 Netsyms Technologies. All rights reserved. Copying is allowed for instructional purposes (such as creating an internal user help document) as long as credit is given and this copyright notice is included. For other purposes, or if you are selling a product containing copied material, please <a href="https://netsyms.com/contact" target="_BLANK">contact us</a> for permission.

Loading…
Cancel
Save