# DS2-core
DS2-core is a lightweight PugJS-based framework for building design systems. 

The design system compiles to mostly pure HTML, SCSS and JavaScript. There are a few enhanced parts that use PHP in order to handle non-critical tasks Zip files on the fly to collect component JavaScript and SCSS. PugJS is used because it can handle some of the automation such as creating includes making components extremely modular.

## Requirements 
The requirements for ds2-core are pretty light. You'll want to be able to process [PugJS](https://pugjs.org/api/getting-started.html) (formerly Jade) and [SCSS](https://sass-lang.com/documentation/) -- and that's about it. 

For our own design system, we use ds2-core with [Prepros](https://prepros.io) (which you can use the Free Unlimited Trial for, but why not splurge and spend the $30USD to support the developer and skip the nags). On MacOS, you could also use [CodeKit](https://codekitapp.com/). 

Alternatively, if you have pre-processor pipelines for Pug and SCSS, which you can install using npm, or any other language you decide to pull in, you can use those to compile if that ends up being easier for you. The framework isn't too picky, so long as things go into the right place. 

## "Installation"

File                          | Processes to 
------------------------------|------------------------------
src/js/scaffolding.js         | public/assets/
src/scss/scaffolding.scss     | public/assets/
src/pg/core/core.scss.pug     | src/scss/
src/pg/core/download.php.pug  | public

All other pug files should compile to from src/pg/ to a relative path of public/*

## Running the core

### Callback functions 
Callback functions can be used in 

- beforeArticleLoad - called before any patterns have started to load 
- success - called when loading a pattern is successful if the result is an HTTP 200
- afterArticleLoad - called after any patterns have started to load 
- done - called when the ajax for any pattern is done, whether successful or not. This is a useful place to load any javascript initializations that pattern. 


## Creating an item


## The content object

The content variable in \/src\/pg\/_config.pug defines your array of patterns. It is made up of the following attributes: 
- name - the hypenated name of the pattern
- status - this should be one of the statuses from your status array
- display - (optional) if present this will be displayed, as is, instead of the name
- template - (optional) [ pug (default) | md ] the file type of a pattern's index file
- core - (optional ) [ true | false ] if true, it will pull from the core folder
- files - (optional) an array of patterns under the parent. 

By changing and resaving the \_config.pug file, (our change is often adding or removing a random space) all of the pug patterns will recompile. Note that md templates will not recompile automatically when config is saved and updated as markdown files don't have an include. 

## Including PugJS in Pug files without compiling
If you wish to include Pug output as code in your instance, you can do this without manually creating a second 'dot container' version of the file. Including files with 'unrecognised' extensions does not compile them. 

1. In your project config, create a Custom Tool called Pug pattern to pug file 
1. Check Process automatically and set the command to 'cp {{input}} {{output}}' on Mac/Linux and 'copy {{input}} {{output}}' on Windows. (This is just your operating system's command line file copy executable.)
1. Set the Output to Relative to input
1. Set the Output Extension to .pug

In your design system implementation, 
1. Create the files that you edit as _[pattern].pp files, and set them to auto compile. (You may wish to let your text editor know what they are, so the syntax highlighting works.
1. Save the file, ensure that it is set to in prepros it is set to process automatically. 
1. Include the .pp file as your pug pattern with .language-pug and include the .pug file as your html output. 

This will ensure that the .pug file will get processed and the .pp file will be handled as text will get compiled, but they should display correctly and remain in sync while maintaining the minimum number of files. 

## Using core code with your own pattern documentation. 
Using 

---
Creating a new pattern
Begin by creating a folder within your strucutre to hold the pattern. Add the folder to your config file. 


Generating css 
You've likely created your component's css as an include file beginning with an underscore. create a second file named the same that includes any dependencies (such as breakpoints) that are required to generate your valid css. 

You can now include the css in your pattern's index file. 

Generating pug
Create a custom tool in prepros, give it a name such as "PP to Pug" set the input extension to .pp and the output extension to .pug and check Process Automatically . The command should be 
Mac / Linux
	cp {{input}} {{output}}

Windows 
	copy {{input}} {{output}}

Once you've added the tool, set the output to "relative path" and set the output extension to pug. For each .pp file you may have to check process automatically as it doesn't always identify the new extension.

You will now be able to include the .pp file in your pattern's index file while including the .pug file which will give a compiled version of your component's html. 


---







## Troubleshooting


## Credits 
This framework includes [PrismJS](https://prismjs.com/) for code syntax highlighting. PrismJS is released under the [MIT license](https://opensource.org/licenses/MIT).
