Browse Source

Update theme documentation

master
Skylar Ittner 1 year ago
parent
commit
0d30870882
1 changed files with 105 additions and 41 deletions
  1. 105
    41
      docs/Theme Development.md

+ 105
- 41
docs/Theme Development.md View File

@@ -11,11 +11,13 @@ This is the folder structure for a standard theme. The root folder shown below
* contact.php
* _default.php_
* _404.php_
* preview.png
* ***colors***
* ***default***
* **green**
* **etc**

If `preview.png` is present, it will be displayed to the user in the theme picker.

## Metadata File

@@ -81,9 +83,9 @@ It is highly recommended to have a contact form template included in your theme.

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 FontAwesome 5 in your theme. The SiteWriter editor allows the user to pick icons from the FontAwesome Free icon set to enhance their content. Use `get_fontawesome_js()` or `get_fontawesome_css()` instead of including FontAwesome in your theme. It saves space and ensures that all themes have the latest version of FontAwesome.

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 company info (business name, phone number, address, and email), social media links (Facebook, Twitter, YouTube, Mastodon, etc), and footer links in the theme. These can be setup in the sitewide settings, and users will expect themes to make use of this information. See the Code Snippets section below for examples of this.

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.

@@ -110,7 +112,7 @@ Below is a minimal functional `default` template that fulfills the above require
<!DOCTYPE html>
<meta charset=`utf-8`>
<title><?php get_site_name(); ?></title>
<script defer src="<?php get_theme_url(); ?>/fontawesome-all.min.js"></script>
<script defer src="<?php get_fontawesome_js(); ?>"></script>
<?php get_header(); ?>
<!-- Navbar -->
<ul>
@@ -132,9 +134,9 @@ Below is a minimal functional `default` template that fulfills the above require
$social = get_socialmedia_urls();
foreach ($social as $s) {
?>
<a class="btn btn-outline-primary m-1" href="<?php echo $s['url']; ?>">
<a href="<?php echo $s['url']; ?>">
<i class="<?php echo $s['icon']; ?> fa-fw"></i>
<span class="sr-only"><?php echo $s['name']; ?></span>
<span><?php echo $s['name']; ?></span>
</a>
<?php
}
@@ -145,7 +147,9 @@ Below is a minimal functional `default` template that fulfills the above require

## Code Snippets

### Plain Text Component
### Components

#### Plain Text

```html
<p class="sw-text" data-component="lead">
@@ -153,7 +157,7 @@ Below is a minimal functional `default` template that fulfills the above require
</p>
```

### HTML Component
#### HTML

```html
<div class="sw-editable" data-component="component-name">
@@ -161,26 +165,31 @@ Below is a minimal functional `default` template that fulfills the above require
</div>
```

### Complex Component
#### Complex

```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>
if (!is_complex_empty("complex-component-name")) {
$comp = get_complex_component("complex-component-name", null, ['icon', 'image', 'link', 'text']);
$icon = $comp['icon'];
$image = $comp['image'];
$link = $comp['link'];
$text = $comp['text'];
?>
<a href="<?php get_url_or_slug($link); ?>" class="sw-complex"
data-json="<?php echo get_escaped_json($btn); ?>"
data-component="complex-component-name" >
<i class="<?php echo $icon; ?>"></i>
<?php echo $text; ?>
<img src="<?php get_file_url($image); ?>" />
</a>
<?php } ?>
```

### Social Media URLs
### Useful Samples

#### List of social media links

```html
<?php
@@ -188,8 +197,9 @@ $social = get_socialmedia_urls();
foreach ($social as $s) {
?>
<li>
<a href="<?php echo $s['url']; ?>" class="icon <?php echo $s['icon']; ?>">
<span class="label"><?php echo $s['name']; ?></span>
<a href="<?php echo $s['url']; ?>">
<i class="<?php echo $s['icon']; ?>"></i>
<?php echo $s['name']; ?>
</a>
</li>
<?php
@@ -197,6 +207,43 @@ foreach ($social as $s) {
?>
```

#### Contact Information
```html
<?php
format_special(
get_setting("address"),
SPECIAL_TYPE_ADDRESS,
'<p><b>Address:</b> <a href="[[CONTENT]]">[[TITLE]]</a></p>'
);
format_special(
get_setting("email"),
SPECIAL_TYPE_EMAIL,
'<p><b>Email:</b> <a href="[[CONTENT]]">[[TITLE]]</a></p>'
);
format_special(
get_setting("phone"),
SPECIAL_TYPE_PHONE,
'<p><b>Phone:</b> <a href="[[CONTENT]]">[[TITLE]]</a></p>'
);
?>
```

#### Footer Links
```html
<ul>
<?php
$links = get_footer_urls();
foreach ($links as $l) {
?>
<li>
<a href="<?php get_url_or_slug($l['link']); ?>">
<i class="fas fa-arrow-right"></i> <?php echo $l['title']; ?>
</a>
</li>
<?php } ?>
</ul>
```

## Theme Functions

### `function get_site_name($echo = true)`
@@ -357,26 +404,24 @@ Get the URL base for the selected theme color asset folder, without trailing sla

### `function 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.
Get the page navigation as a string containing a series of <li><a></a></li> elements.

Format:
**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>
```
<li class="$classPrefix$slug $liclass $currentclass">
<a class="$linkclass $currentlinkclass" href="url">
Link Text
</a>
</li>

Other pages:

<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.
@@ -408,8 +453,27 @@ Echos or returns a URL for the FontAwesome 5 CSS WebFont.
* **Parameters:** `$echo` — `boolean` — default true
* **Returns:** `string` —

### `function get_footer_urls()`

Return an array [[title, link], [title, link]] of links for the page footer

### `function get_socialmedia_urls()`

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

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

### `function format_special($text, $type = SPECIAL_TYPE_NONE, $template = "", $title = null, $echo = true, $conditional = true)`

Take $text, format it according to $type, replace [[CONTENT]] in $template with it, and replace [[TITLE]] with $title (or the unchanged $text if $title is null)

$type may be one of the following: <ul> <li>`SPECIAL_TYPE_PHONE`: `tel:1234567890`</li> <li>`SPECIAL_TYPE_EMAIL`: `mailto:address@example.com`</li> <li>`SPECIAL_TYPE_LINEBREAKS`: Replaces `\n` with `<br />\n`</li> <li>`SPECIAL_TYPE_ADDRESS`: Creates a link to open Google Maps, and runs LINEBREAKS on $title</li> <li>`SPECIAL_TYPE_NONE`: Does no text manipulation.</li> </ul>

* **Parameters:**
* `$text` — `string` —
* `$type` — `int` —
* `$template` — `string` —
* `$title` — `string` —
* `$echo` — `boolean` — default true
* `$conditional` — `boolean` — Act as output_conditional() and not return anything if $text is empty
* **Returns:** `string` —

Loading…
Cancel
Save