Readme
parent
76de859b21
commit
88b2dbfa6e
@ -1,75 +1,35 @@
|
|||||||
Business App Template
|
TodayStream
|
||||||
=====================
|
===========
|
||||||
|
|
||||||
This is an empty (but fully functional) PHP application. It is designed to
|
TodayStream is a news/headlines reader and weather app. It is designed in a
|
||||||
integrate with AccountHub, an account management web interface. AccountHub manages
|
modular fashion, to make adding data sources easy.
|
||||||
user credentials and account data, and is accessed by this app via [a simple API](http://docs.netsyms.com/docs/AccountHub/API%20Documentation/).
|
|
||||||
|
|
||||||
[<img src="https://api.codacy.com/project/badge/Grade/2aeadc6b65d545c4a4c2e77d286373fd" alt="Codacy badge">](https://www.codacy.com/app/Netsyms/BusinessAppTemplate?utm_source=github.com&utm_medium=referral&utm_content=Netsyms/BusinessAppTemplate&utm_campaign=Badge_Grade)
|
TodayStream ships with support for NewsAPI.org, Reddit, and DarkSky APIs.
|
||||||
|
With the exception of Reddit, you'll need to obtain and set API keys in
|
||||||
|
`settings.php` for TodayStream to be useful.
|
||||||
|
|
||||||
Program Structure
|
It currently determines the user's location for weather information based on IP
|
||||||
-----------------
|
address. You'll need to download the (free) MaxMind city-level geoIP database
|
||||||
|
and keep it up-to-date. Other methods of obtaining location, such as with
|
||||||
|
JavaScript APIs and user-configurable settings, are coming soon.
|
||||||
|
|
||||||
### Folders
|
This application does not and will not store user location on the server.
|
||||||
* api
|
|
||||||
An API framework. See api/apisettings.php below.
|
API responses are cached in the database for a reasonable amount of time, to
|
||||||
* api/actions
|
decrease latency and reduce (or eliminate) API costs. News item thumbnails are
|
||||||
A place to put your API actions.
|
resized and stored in `cache/thumb`.
|
||||||
* langs
|
|
||||||
Translations and alert messages.
|
|
||||||
The language files that are loaded depends on the value of `LANGUAGE` in `settings.php`.
|
|
||||||
All .json files in a language folder are parsed and loaded into the dictionary (use via `$Strings->get('some key')`).
|
|
||||||
* lib
|
|
||||||
A good place to put helper functions that you don't want "in the way". All files that end with `.lib.php` are automatically loaded.
|
|
||||||
* pages
|
|
||||||
What it looks like. If you go into `pages.php` and define a page with the name `foo`, there should be a `foo.php` in here.
|
|
||||||
The app checks before loading, so it will give a friendly 404 error if it doesn't find your page.
|
|
||||||
Woe to you if you delete `home.php` or `404.php`, as those are assumed to exist for fallback behavior.
|
|
||||||
* static
|
|
||||||
CSS, JavaScript, fonts, images...
|
|
||||||
* vendor
|
|
||||||
If you don't know what this is about, or you don't have it, you need to read up on Composer. Right now.
|
|
||||||
|
|
||||||
### Files
|
|
||||||
* settings.template.php
|
|
||||||
App configuration. Copy to `settings.php` and customize. Documented with inline comments.
|
|
||||||
* app.php
|
|
||||||
Handles the web part of the app. If you have problems with too many items on the navbar, change `$navbar_breakpoint`.
|
|
||||||
To change the navbar colors, find and edit `<nav class="navbar ...`, changing `navbar-dark bg-blue` to suit.
|
|
||||||
* static/img/logo.svg
|
|
||||||
The app logo. Should be a square, we don't test any other sizes.
|
|
||||||
* required.php
|
|
||||||
The "duct tape" that holds the app together. Use `require_once __DIR__."/required.php"` at the top of every file.
|
|
||||||
It loads Composer dependencies, library files, app settings, language data, and creates `$database` for accessing the database.
|
|
||||||
It also has some utility functions, including `dieifnotloggedin()`.
|
|
||||||
Read through it to see exactly what it does.
|
|
||||||
* action.php
|
|
||||||
A good place to put form handling code. By default it only handles logging out, but is easily expanded.
|
|
||||||
* api/apisettings.php
|
|
||||||
An array of API actions. Validates any variables required by your actions before running them. See https://source.netsyms.com/Apps/NotePost/src/branch/master/api/apisettings.php for a full example of its capabilities.
|
|
||||||
* api.php
|
|
||||||
Legacy shim for code that still expects the API endpoint to be here.
|
|
||||||
* index.php
|
|
||||||
Handles login and checking permissions.
|
|
||||||
* app.php
|
|
||||||
Main app page after login. Handles loading app pages and 404 errors.
|
|
||||||
Redirects to `index.php` if the user is not logged in.
|
|
||||||
Note: to show an alert message (success, error, whatever), set the GET argument `msg` to a message ID from `lang/messages.php`.
|
|
||||||
* pages.php
|
|
||||||
Define app pages/screens in an array. The page ID/array key is assumed to exist as a file `pages/{key}.php`, or it will 404.
|
|
||||||
__Optional parameters:__
|
|
||||||
`'navbar' => true` will show the page as a button in the app menu bar.
|
|
||||||
`'icon' => '...'` will show an icon from FontAwesome in the menu bar. Setting this to `home` will show the icon `fa-home`.
|
|
||||||
`'styles' => ["file.css"]` will inject the listed CSS files into the page header (after all other CSS, like Bootstrap).
|
|
||||||
`'scripts' => ["file.js"]` will inject the listed JavaScript files into the page footer (after jQuery and other builtin scripts).
|
|
||||||
* langs/messages.php
|
|
||||||
Array of alert messages.
|
|
||||||
`"string"` is the language string for the message, `"type"` is one of `success`, `info`, `warning`, or `danger` (i.e. Bootstrap alert classes).
|
|
||||||
Changing the type changes the icon and color of the alert box.
|
|
||||||
|
|
||||||
|
|
||||||
Setup Tips
|
Setup Tips
|
||||||
----------
|
----------
|
||||||
|
|
||||||
* Run composer install (or composer.phar install) to install dependency libraries
|
* Run composer install (or composer.phar install) to install dependency libraries
|
||||||
* If you don't have any color in the navbar, run `git submodule init` and `git submodule update`.
|
* If you don't have any color in the navbar, run `git submodule init` and `git submodule update`.
|
||||||
|
|
||||||
|
|
||||||
|
-----
|
||||||
|
|
||||||
|
|
||||||
|
Required attribution: This product includes GeoLite2 data created by
|
||||||
|
MaxMind, available from http://www.maxmind.com
|
Loading…
Reference in New Issue