▲▼
darkwave — 0.4.0
dw - specialized functionality/components/patterns for building complex web applications quickly -- toolkit for building custom admins and the sites they power DW internet application development system - a software development kit for building complex applications quickly, with the littlest amount of technical overhead (building things in a responsible way, easy-to-maintain complex functionality) LAMP-based ADK (application development kit)

INSTALLATION

# installation updates -- dw init checklist -- - [x] create subdomain/domain - [x] & ftp (if necessary) - [x] add profile (ftp creds) to coda - [x] create database - [x] & user - [x] add db creds to coda (if necessary, not needed for eqkh/purhost sites) - [ ] ** always use innodb/utf8 ** (myisam is default on most systems, but innodb is what you want) - [x] download dw from darkwave.ltd & upload files to ftp & visit site to install - [ ] 'install' modules -- currently everything is based on blog -- https://github.com/hxgf/dw-blog-ui -- https://github.com/hxgf/dw-blog-stereo sites setup checklist add (for me personally) - automated mysql backups - automated git backups dw install instructions / requirements - file/folder perms (writeable/editable files/dirs need to be 755) - galleries - php upload max size / max post size (set w/ host or htaccess) - imagemagick - possibly allow_url_fopen? dw checklist reminder to update max filesize (outside scope of fw, but something you still need to do in some cases) dw install - create the db & user on your own (reqs for user perms, db creation) - put the files on your server (w/ ftp) - requirements - lamp stack (apache w/ htaccess & speficif modules enabled)(instructions for doing it w/ nginx) - chmod some files? - go to the site & run the install prerequisites - php (version?) - mysql (version?) - db already set up w/ username & pw 1. download zip & put it on your server (go to the site, do the install thing) 2. delete the install file (controllers/install.php) (the installer should delete itself when it's done, but just in case, you should do it) 3. have a good time! [it's pretty much stereo & tachyons from this point, so look at the docs for that] - upload folder needs to be set to 755 (correct?) creating a new user: $email = "nacho.pizza@gmail.com"; $password = "pencil69"; $screenname = "admin69"; $new_id = db_insert("users", array( 'email' => strtolower($email), 'password' => password_hash($password, PASSWORD_BCRYPT), 'group_id' => '1', 'date_created' => time(), 'url_title' => url_title($screenname), 'screenname' => $screenname, )); echo $new_id; - ideal setup - php7 - ssd host/vps - requirements - upload (max filesize, post filesize, etc) - note upload perms (www-data, 0755) - imagemagick - mysql (version?) - php (version?) - apc (recommended) - curl - prefs - image upload path - markdown - timezone dw php.ini - post_max_size = 20M - upload_max_filesize = 20M - curl needs to be enabled - mail (postfix might be needed on some hosts) ?? dw install - put labels or "info" mouseovers automatically add/remove "http(s)" where needed remove trailing slashes where needed on success show success message don't link to admin unless there's been an admin created is there a way to re-initialize the install process (in case you decide later that you want to install an admin? just want to get started with the site architecture first?) - install process error reporting (files need to be writeable? db errors? missing fields? etc?) install reqs mysql user that can create/alter tables ability to write to filesystem darkwave reqs imagemagick (version?) install better logic? idk...just make damn sure there are no errors before it deletes itself catch errors better & show them & have a friendly "go back and fix" message - install script - pre-check (so you can see which features are available...tell people what they need to change in order to make it compatible...maybe offer a script?) ------ ------ ------

dw is: - stereo - extensible admin app - content mgmt - simple auth system - web-app primitives (image management, file uploads, etc) - future: data manager - future: code/file manager -- can edit/manage the entire app from here - helpful error messages for things like uploads, logins, etc - form handling and validation (primitives, checking required/type, etc) - a consistent and reliable (unchanging) architecture to build against pragmatic, ehthos, brutalist, simple, boring, fast, fun - helper js libraries (dropzone, smoke, etc) - copy/paste components/patterns / building blocks for building specific types of functionality - pre-packaged 'manual plug-in' functionality - recommendations for tools to use for solving problems that aren't solved w/ the system - tutorials /checklists for how to build certain kinds of things w/ this (every time you want to do this, here's what you need to do/consider) talking 'newbs' through more complex operations (kinda like coaching someone through disarming a bomb or hooking up a sound system) (and helpful notes for debugging - [ie "photo uploads not working? check to make sure you created the upload folder and that it has the right permissions]) recipe / cookbook how to build a directory of profiles for your organization generic blog site todo list app haha podcast cms? need MORE POWER? build an obelisk! here's how! ------ ------ ------

KITCHEN SINK - db collection init scripts - copy/paste admin screens (blog?) - generic form/photo updating from DAA user/trade/project - kitchen sink form w/ every type of input / data structure - corollary copy/paste "front end" components (?? OIP blog, files)

# DOCS / EDUCATION / TUTORIALS [ ] better docs (describe what the system actually does, how to work with it, how to extend it) // foundational info // what it does // what it includes // why would you use it wow this readme has drop-downs, cool to do that for dw readme? https://github.com/lydiahallie/javascript-questions#readme meta - need to suppress php warnings? (filling up the log file?) try this: error_reporting(E_ERROR | E_PARSE); a manual (/field guide) for building (effective/attractive/solid/usable) web sites/applications with as little (fanfare/suffering/pretense/) as possible key concept: build your thing, call it done, go hang out with your friends development is central to some people's lives, but you're a real person with a real life. you can over-engineer anything to death, if you're a perfectionist, you'll never be happy with it, there's always something that could be better make it good enough (and do a really good job), but know when to stop and call it done instructional guides and resources (links to valuable online tools/libraries that can help you solve problems quickly) - what's included for the admin (and can be included in your public site) - font awesome, tachyons, alpine, quill, dropzone, etc -- links to all the docs for all the libs dw docs want to have a reference of all commonly used docs for all the libs included (font awesome icon search, tachyons components, etc) - copy/paste for FE components/patterns (& link to whatever repos for back end code? copy/pasta?) - front end / dev resources --- want to have a collection of cool "approved" libraries (ones that we like working with and yield badass results, ideally fitting the same license and ethos of the projects) dw docs? separate site/resource? - front end best practices - want to have a site (that i can refer to) that documents the workflows, resources and best practices i use/need to be a productive and efficient FE dev - notes of all the tools i use for various things (unix time format, generating favicons, etc) stereo/dw front end -- if you want equal height floated divs, use flex + flex-wrap -- http://tachyons.io/docs/layout/flexbox/ also if you do a flexbox sticky footer, the flex element needs to be ie11 compliant w/ min height the flex element needs to have `flex: 1 0 auto;` - Is darkwave for me? -- guide/quiz/questionaire about the type of project you want to build, it tells you wether or not it's a good fit, offers alternatives if it's not (you need laravel, rails, wordpress, etc) Dark wave light house score? - https://blog.logrocket.com/building-a-progressive-web-app-pwa-no-react-no-angular-no-vue-aefdded3b5e cookbooks for doing various types of projects (simple web site apps \-\-> mobile/pwa apps [tv os, "platform" type cloud services]) my "best-practices" guide for putting stuff together "recipes" "spells" cool "how-to" instructions, step-by-step guides with colorful commentary "building a forum / iphone app w/ darkwave, lexxi, vue, and phonegap" or whatever recommendations for cool microservices to work with (braintree, mailgun, compose, etc) tips on workflow, setting up your environment, etc stereo/dw - this is cool for doing shit locally https://github.com/typicode/hotel idk mamp? open source alternative? recommended editors (atom, coda, iterm, sequel pro, etc) here's what's included (libs) flatpickr https://chmln.github.io/flatpickr/ dropzone smoke tachyons font awesome jquery phmagick [we're using them in the admin, it's up to you wether or not to use them in your actual projects. we made a note of patterns that utilize these dependencies for customer-facing code] - make a note of all the 3rd-party libs & functionality the system comes with (stereo + phmagick + js libs + tachyons + darkwave functions [new_user (back end), post_json (front end) idk what else]) - tachyons components / resources [[tachyons patterns / meta]] - datepicker, quill, dropzone, smoke, etc comes bundled with jquery [version?] js cookie jquery text editor dropzone smoke flatpickr phmagick [darkwave helpers, loaders animations, etc, idk] tachyons dw/stereo docs - all available global vars ($GLOBALS['user_id'], $GLOBALS['auth'], etc) global vars you have at your disposal user_id // same as cookie profile_url // same as cookie auth // is user authenticated? is_admin // is current user in admin group? is_moderator // is current user in mod group? locals // template locals site_title site_code site_url [and all the settings variables] front end tools darkwave.api_request({ url: '/', // required data: {}, callback: function(result){ alert(result); }, debug: true // optional }); auth emails (welcome, pw reset) are sent with notifications@yourdomain.com. if you want to change this, do it yourself...you don't need to have a valid mailbox there, but set one up if you want to catch any replies from people. how to use/extend .validate (checking for uniqueness with email addresses or whatever else you want) how to check for required form fields here's what comes with auth: /login /register & activation process /forgot & pw reset process /account/settings here's the default behavior and here's how you can customize it ------ ------ ------

more power?

need more power? maybe you should build an obelisk - if you have more than one darkwave app running on a server and/or you want fast/concurrent processing w/ node.js (do the fast and heavy lifting that php isn't particularly well-suited for doing) - generic dw-compatible microservices that can be utilized by multiple apps - http interface (you call it from the dw controllers, send it data/instructions via http api)

TEMPLATES

--- DW components gh (save components for docs & delete from gh) https://github.com/hxgf/dw-core-ui https://github.com/hxgf/dw-blog-ui https://github.com/hxgf/dw-blog-stereo https://github.com/hxgf/dw-shop-ui https://github.com/hxgf/dw-shop-stereo https://github.com/hxgf/dw-contact-ui https://github.com/hxgf/dw-contact-stereo https://github.com/hxgf/dw-sitemap-ui https://github.com/hxgf/dw-profile-ui https://github.com/hxgf/dw-newsfeed-ui https://github.com/hxgf/dw-message-ui https://github.com/hxgf/dw-map-ui https://github.com/hxgf/dw-forum-ui https://github.com/hxgf/dw-event-ui https://github.com/hxgf/dw-directory-ui https://github.com/hxgf/dw-classifieds-ui --- delet https://github.com/hxgf/dw-core-lexxi https://github.com/hxgf/dw-blog-lexxi --------------- dw docs integration recipes for adding new functionality [i really want to automate the installation of this from either the web admin or the cli] 1. add the controllers 2. link to the new files 3. add the templates 4. add any js/css/images 5. add any db tables how does form validation work? which classes should you put where? and why? (validate, required, etc) building admin screens using the save/delete handlers (how they work, what they expect, etc) document how the login works (note that we have a field called "website" to fool bots) "zero to deployment" guide which talks about hosting, ideal enviornments, etc (for total noobs, not part of the fw, but good ideas to remember when setting up your site / solving this particular problem) uploads make sure your uploads folder is set to 755 if it's not working, turn on debugging and check this shit out: https://www.startutorial.com/articles/view/move_uploaded_file-faq




something something templates go in ./pages and you can call them whatever you want. you can organize this however you want, too! link to handlebars docs for more info.
Basic Variables

the simplest thing to do. if you use render_template, stereo includes a few by default (year, etc) as well as a few special things (is_admin, auth, user_id, etc) (title [uses the site title by default, so it's kinda optional])

php


	$app->get('/variable-example', function(){
	  $GLOBALS['app']->render_template(array(
	    'template' => 'demo',
	    'data' => array(
	      'fish' => 'salmon',
	      'dish' => 'paella',
	      'planet' => 'Nibiru'
	    )
	  ));
	});

hbs (note about literals { { { } } } vs { { } } -- by default hbars doesn't parse html tags, so if you want to have them rendered, do this)


	<h2>Simple Variables Example</h2>
	<h3>Cool Fish: {{fish}}</h3>
	<h3>Cool Dish: {{dish}}</h3>
	<h3>Cool Planet: {{planet}}</h3>
Iterating Arrays

it's hella easy, just like a foreach loop. you can even nest the arrays to infinity (and beyond) (sorry) (it can be as simple or complex as you want to make it) (see the demo controller/templates for an example of more complex array iteration)

php (simple & complex example from demo)


	$app->get('/array-example', function(){
	  $GLOBALS['app']->render_template(array(
	    'template' => 'demo',
	    'data' => array(
	      'snacks' => array(
	        'Carrots',
	        'Hay',
	        'Sugar Cubes',
	        'Oats',
	        'Apples',
	        'Weaker Horses'
	      )
	    )
	  ));
	});

hbs (simple & complex example from demo)


	<ul>
	  {{#each snacks}}
	  <li>{{this}}</li>
	  {{/each}}
	</ul>
Simple Logic

you can do some simple logic to check if a variable exists (or has value). if you would like to do more complex logic, check out [if_either], [in_array], [is]

php


	$app->get('/logic-example', function(){
	  $GLOBALS['app']->render_template(array(
	    'template' => 'demo',
	    'data' => array(
	      'fish' => 'salmon',
	      'dish' => 'paella',
	    )
	  ));
	});

hbs (if/else, unless, (normal hbars logic, link to hbars docs) maybe is & link to helpers)


	{{#if fish}}
	 Salmon is available
	{{else}} // this won't show:
	 No salmon for you.
	{{/if}}
	
	{{#unless snacks}}
	 No snacks available. We have {{dish}}, though.
	{{else}} // this won't show:
	 Look at all the snack options:
	 {{#each snacks}}
	 - {{this}} <br />
	 {{/each}}
	{{/unless}}
Partials

You can include templates in other templates! That is neat! all your partials need to be in the _partials directory, but you can organize that however you want!

normal php whatever example


	$app->get('/partials-example', function(){
	  $GLOBALS['app']->render_template(array(
	    'template' => 'demo',
	    'data' => array(
	      'fish' => 'salmon',
	      'dish' => 'paella',
	      'planet' => 'Nibiru'
	    )
	  ));
	});

hbs


	<h2>Demo page (rendered with partial from separate template)</h2>
	
	<h3>Fish: {{fish}}</h3>
	<h3>Dish: {{dish}}</h3>
	
	{{> planets-partial}}

hbs (partial code) (see how it has access to the same data?)


	<ul>
	  {{#each planets}}
	  <li>{{this}}</li>
	  {{/each}}
	</ul>
Global Layouts

if you want to use a global header footer, you can! you can define as many global wrappers/layouts as you want (like express, django, ember, whatever...wow!) if you leave the "layout" parameter blank, STEREO will use the layout in ./pages/_layouts/base.hbs by default. your content will be rendered where the [[outlet]] part is

php example


	$app->get('/layouts-example', function(){
	  $GLOBALS['app']->render_template(array(
	    'template' => 'demo',
	    'title' => 'Site Title Whatever',
	    'layout' => 'admin',  // false for nothing, base by default
	    'data' => array(
	      'fish' => 'salmon',
	      'dish' => 'paella',
	      'planets' => array(
	        'Mercury', 'Venus', 'Earth', 'Nibiru'
	      )
	    )
	  ));
	});

hbs (wrapper)


	<!DOCTYPE html>
	<html>
	<head>
	  <title>{{title}}</title>
	  <meta charset="utf-8" />
	  <meta http-equiv="X-UA-Compatible" content="IE=edge, chrome=1" />
	  <link rel="stylesheet" href="/css/app.css" />
	</head>
	<body>
	
	  <div class="header"><h1>Site Title Whatever</h1></div>
	
	  <div class="container">
	    [[outlet]]  // this is where the content will be rendered
	  </div>
	
	  <div class="footer">(c) {{year}} -- All rights reserved or whatever.</div>
	
	<script src="/js/vendor/jquery.min.js"></script>
	<script src="/js/app.js"></script>
	
	</body>
	</html>

hbs


	<h2>Demo page (rendered with global wrapper)</h2>
	
	<h3>Fish: {{fish}}</h3>
	<h3>Dish: {{dish}}</h3>
	
	<ul>
	  {{#each planets}}
	  <li>{{this}}</li>
	  {{/each}}
	</ul>
Template Locals (Global Variables)

need to make an arbitrary variable/array available to all the templates? use $GLOBALS['locals'] (hold for laugh) but seriously, folks, treat it like an array and whatever you need. and if it's an array is something you can iterate over. and, of course, all of this is available to the application as $GLOBALS['locals']['numbers'] or whatever

php example


	$GLOBALS['locals']['eat_this'] = "breakfast";

hbs


	Let's have {{locals.eat_this}} for dinner.

php example


	$GLOBALS['locals']['colors'] = array('red', 'salmon', 'lilac', 'azul');

hbs


	<ul>
	  {{#each locals.colors}}
	  <li>{{this}}</li>
	  {{/each}}
	</ul>