You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+28-70Lines changed: 28 additions & 70 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,61 +4,32 @@
4
4
</div>
5
5
<hr>
6
6
7
-
Jerpy a small, zero-dependency, flat-file content management system (CMS) built for control and simplicity that is easy to installs, customize, and maintain.
7
+
Jerpy a small, zero-dependency, flat-file simple website system built for control and simplicity that is easy to install, customize, and maintain.
8
8
9
-
**This was built to be as streamlined and stripped-down as possible, so it's meant to be administered directly via the files and there's no admin web panel.**
9
+
Jerpy doesn't have a management interface or web portal (there *could* be a [plugin](#plugins) for that...). Everything is managed directly via the files themselves.
10
10
11
11
# Getting Started
12
12
## Composer
13
-
Jerpy is super easy to get setup. Simply run the following to create a new project:
All site settings are set in the `config.php` file, including timezone override, selected layout, enabled plugins, and page routes.
21
-
22
-
## Layouts
23
-
The `layouts` directory stores layout templates, each their own `.php` file. The default global theme is set in `config.php` via the `$layout` property.
24
-
```
25
-
🗀 layouts
26
-
🗋 default.php
27
-
```
28
-
```php
29
-
$layout = 'default';
30
-
```
31
-
32
-
## Assets
33
-
This is the global assets directory, in which you can organize your CSS, JavaScript, fonts, and images to use in your layouts and pages via absolute URI:
The `media` directory is for any and all URL-accessible files.
49
-
50
-
## Content
51
-
The `content` directory is for all your embedded content files, such as Markdown text files, and is not URL-accessible.
17
+
# Files & Folders
18
+
-## `config.php`
19
+
Set the timezone override, selected layout, enabled global plugins, and page routes here.
20
+
-## `layouts`
21
+
Stores layout templates, each their own `.php` file. The default global theme is set in `config.php` via the `$layout` property. The value is just the file name with no extension.
22
+
-## `assets`
23
+
Organize your CSS, JavaScript, fonts, and images to use in your layouts and pages via absolute URI here:
24
+
-## `media`
25
+
For any and all URL-accessible files, such as documents, video/music, etc.
26
+
-## `content`
27
+
For all your embedded content files, such as Markdown text files, and is not URL-accessible.
52
28
53
29
## Pages & Routes
54
-
The `pages` directory stores the page contents for the site, and are configured for each route in `config.php`.
55
-
56
-
Each route is an associative array of a `page` key, and optional `meta` and/or `layout` keys.
57
-
The `page` key value is the path to your page file within the `pages` directory.
58
-
The `meta` key value is an associative array of whatever metadata you want to use in your layout/page, i.e. title, description, etc.
59
-
The `layout` key value is either `false`, meaning no layout is used and the page is rendered as is, or the filename of a different layout than the default.
30
+
Routes are configured in an associative array of a route key and page value. The value can be either a string or an associative array. If a string, the value is rendered using the default template, and the string is expected to be the filename of a page in the pages folder. If an associative array, there must be at least a `page` key and value. Optionally, a `meta` key and value can be set to include metadata for the given route, as well as a `layout` key and value to override the default layout, or not use one at all.
60
31
61
-
See the example routes below:
32
+
Example routes config:
62
33
```php
63
34
$routes = [
64
35
'/' => [
@@ -73,16 +44,17 @@ $routes = [
73
44
'title' => 'About Us',
74
45
'thumbnail' => '/assets/my_thumbnail.png'
75
46
],
76
-
'layout' => 'different_layout'
47
+
'layout' => 'layout_2'
77
48
],
49
+
'/simple/page' => 'simple_page.php',
78
50
'/page/without/layout' => [
79
51
'page' => 'some_page.php',
80
52
'layout' => false
81
53
]
82
54
]
83
55
```
84
56
85
-
You can implement your metadata properties in your layout, such as for social media SEO tags, using the `<meta>` tag. Use the `@` warning suppressing syntax for times when a route does't have that metadata property specified:
57
+
When implementing metadata, use the `@` warning suppression syntax to avoid warnings when a route does't have that metadata property specified:
86
58
```html
87
59
<head>
88
60
...
@@ -93,8 +65,8 @@ You can implement your metadata properties in your layout, such as for social me
93
65
</head>
94
66
```
95
67
96
-
###Dynamic Routes
97
-
You can also specify non-static matching routes for the key string. Use the `:param` syntax to dynamically match a route and have its parameters set to the parsed values from the incoming URI:
68
+
## Dynamic Routes
69
+
To use dynamic route parameters, use the `:param` syntax in the route key string. All matches values will be accessible from the `$params` variable:
98
70
```php
99
71
$routes = [
100
72
'/products/:id' => [
@@ -104,30 +76,20 @@ $routes = [
104
76
```
105
77
`product.php`:
106
78
```php
107
-
<p>ID: <?= $req->params->id ?></p>
79
+
<p>ID: <?= $params['id'] ?></p>
108
80
```
109
81
110
82
# Templating
111
-
PHP's built-in templating is sufficient for most websites. As such, just use `include` and `require` as you would normally for templating your site, parsing content as needed (see [plugins](#plugins) below).
83
+
PHP's built-in templating is sufficient for most websites. As such, just use `include` and `require` as you would normally for templating your site, parsing content as needed (see [plugins](#plugins)).
112
84
113
-
## Global Variables
114
-
There are a couple of global variables you can always reference in a layout or page file: `$req` and `$page`.
85
+
# Global Variables
115
86
|Name|Data Type|Note|
116
87
|---|---|---|
117
-
|`$req`|`object`|The current request (see [request](#request) below)|
88
+
|`$uri`|`object`|Clean URI value|
89
+
|`$params`|`array`|Any metadata key/values specified for the matched route|
118
90
|`$page`|`string`|Path to the page file being rendered|
119
91
|`$meta`|`array`|Any metadata key/values specified for the matched route|
120
-
121
-
# Request
122
-
The request object (`$req`) contains a handful of useful properties and methods:
123
-
|Name|Data Type|Note|
124
-
|---|---|---|
125
-
|`$req->uri`|`string`|The current requested route, i.e. `/about`|
126
-
|`$req->method`|`string`|The request method, i.e. `GET`, `POST`, `PUT`, `DELETE` etc.|
127
-
|`$req->query`|`object`|Any query parameters passed in the URL|
128
-
|`$req->params`|`object`|Any dynamic parameters parsed out from the requested route|
129
-
|`$req->body(string $mime)`|`method`|Returns any data sent with a `POST` or `PUT` request. Specifying a MIME type argument will return a parsed object of the data|
130
-
|`$req->files(string $field)`|`method`|Returns an array of any uploaded files for a form field sent with a `multipart/form-data` type request|
92
+
|`$layout`|`array`|Current layout|
131
93
132
94
# Plugins
133
95
Plugins can be created to extend or add functionality to Jerpy. They do not require any specific framework nor follow any particular design pattern. The only requirement for plugins is that the entrypoint is a `.php` file with the same name as the plugin's folder. From there, you can use whatever preferred tools and package managers to create the plugin code, such as Composer.
@@ -141,15 +103,11 @@ Plugins can be created to extend or add functionality to Jerpy. They do not requ
141
103
🗀 someSupportingPackage
142
104
```
143
105
144
-
Plugins are loaded globally, and their top-level objects, functions, and/or classes are accessible from all layouts and pages.
145
-
146
-
To add a plugin, simply copy/upload the plugin's folder to the `plugins` directory.
147
-
148
-
To enable a plugin, add it's folder name to the `$plugins` array in `config.php`.
106
+
Plugins can be included/required on a given page file as needed, or you can load it globally to be used on every page. To add a plugin, simply copy/upload the plugin's folder to the `plugins` directory. To enable a plugin globally, add it's folder name to the `$plugins` array in `config.php`.
149
107
150
108
Below is an example plugin for using Parsedown via a wrapper method:
151
109
152
-
**NOTE: When including/requiring files within a plugin, make sure to use the `__DIR__` global to ensure PHP looks *within* the plugin directory and not in the root directory**
110
+
**NOTE: When including/requiring files within a plugin, make sure to use the `__DIR__` global to ensure PHP looks *within* the plugin directory and not in the root directory of the site**
0 commit comments