Introduction to HTML static page prototype delivery tool "Magic Card"

1. "Magic Card" debut

That's right, "Magic Card" is the "Magic Card" in the Magic Card Girl Sakura, which is a homonym of the word mockup. The following is the "Magic" spokesperson Maika Sakura, Dangdangdang!

Moka spokesperson

Although the "Magic Card" project is linked to my github account, many projects have been run within the reader. The writer line, Tencent video reading, and some internal systems are all developed with the help of "Magic Card". From 17 years to the present, it has been iterated a lot, and it is currently in a relatively mature state, so it is time to show it to everyone.

"Magic Card" project address: https://github.com/zhangxinxu/mockup

2. The background of the birth of "Magic Card"

Ideal: big front end, engineering, separation of front and back ends, modular development;
reality: big brother, what are you? We only need HTML static pages. What are you doing!

At present, there are still many teams who are still developing the traditional back-end development page. Even large and mature front-end engineering development companies will have similar requirements. For example, the development of old and old internal systems of the company, for example, when inter-departmental or collaboration with remote teams, the other party hopes that the front-end reconstruction and delivery is high-quality HTML Prototype pages, at this time, no automation tools, front-end templates and other high-tech are needed, because the development of docking can't be played, and I don't bother to play.

It’s time to return to the painful past, for example:

The head and tail of traditional static HTML pages cannot be shared. There are more than 20 pages. If the public header changes, there are many places to change. Tired!
Things like variables in Sass that are so useful are not supported. If all the rounded corners change from 2px to 4px, the replacement will not be possible.
Some interaction effects require real Ajax requests. Traditional static HTML can only be previewed using the file protocol by default, and Ajax requests cannot be restored. It is necessary to install and configure Apache or IIS to simulate the service environment. This is very annoying, and it is difficult to install it on your own computer. As a result, it hiccups when you use the conference computer to demonstrate Fart. When the product and development unzip your compressed package experience, asynchronous loading is completely wiped out, and the page effect is miserable. You said, it's a big deal, it's necessary to install an environment. Okay, I installed it, and I saw the installation tutorial. It took more than a dozen steps and I couldn't go wrong. I think the marriage process was not so long that year, and the whole person is not good.
There is no resource merging function on the development side. The front-end can only manually write JS and CSS together, and future maintenance depends on dazzling.

The contradiction arises: what the transfer party wants is a clean HTML prototype, not an HTML page coupled with front-end engineering; while front-end students hope that front-end engineering can be used during development to facilitate rapid development and easy maintenance.

Is there any way to take care of this at the same time and deal with this contradiction?

Such pain points prompted the emergence of "Magic Cards". Free installation, directly hit the pain points of static page development, improve development efficiency and reduce maintenance costs.

2. Introduction to "Magic Card"

"Magic Card" is a Node.js gadget that enables some dynamic features to help front-end personnel complete high-fidelity static prototype pages with super high quality and high efficiency . It is purely native, without any installation package dependencies, and is very lightweight.

Usually the back-end development is based on many windows machines. Therefore, the run.bat file is also prepared, which can be run by double-clicking it. Product students can also play, and developers can also play.

It is much simpler than the engineering set, and there is no messy npm package installation problem.

Main functions of "Magic Card":

HTML import function, the head and tail can be shared
Combination strategy of CSS and JS resources based on folders
Support CSS variables and @import module introduction
```
@import url(../_variable.css);
```
One-click opening of the local http environment, easy simulation of post/get requests

Demo demonstration, based on the prototype page generated by "Magic Card": index.html

3. How to use?

Download the project zip package (including the default scaffolding): master.zip
Install node.js
The command line node run. Windows system can double-click run.bat.

At this time, the "Magic Card" opens the local service, http://127.0.0.1:2019/views/html/*.html access (127.0.0.1 can also be replaced with localhost). Here 2019 is variable and is set based on the current year.

At the same time, comprehensive monitoring of HTML, CSS and JS resources.

Template directory structure:

./src -> HTML, JS, CSS resource development directory 
  |--static 
  | |--css 
  | | | |--common 
  | | | | |--reset.css 
  | | | | |--color.css 
  | | | | --layout.css 
  | | | |--animate.css 
  | | |--details 
  | | | | |--home.css 
  | | | | |--page1.css 
  | | | |--page2.css 
  | |- -js 
  | | |--common 
  | | | | |--lib 
  | | | | |--jquery.js 
  | | | | |--header.js 
  | | |--home 
  | | | | |--home.js 
  | | |--pages 
  | | | |--page1.js  
  | | | |--page2.js
  |--views
  | |--html 
  | | | 
  --include 
  | | | | |--meta.html 
  | | | | |--header.html | | | |--footer.html 
  | | | |--index.html 
  | | |- -page1.html 
  | | |--page2.html 
./dist -> Preview and final resource delivery directory 
  |--static 
  | |--css 
  | | |--common.css 
  | | | |--details.css 
  | | --js 
  | | |--lib 
  | | | | |--jquery.js 
  | | | |--common.js 
  | | | |--home.js 
  | | |--pages.js 
  | |--images 
  | |- -fonts 
  |--views  
  | |--html
  | | |--index.html 
  | | |--page1.html 
  | | |--page2.html 
  | |--cgi 
  | | | |--succ.json 
  | |--map.html -> Map and project progress page

among them:

./src To develop the catalog, you can see that the resources are divided into more detail according to modules or pages
./dist To generate the catalog, prototype preview, and static resource delivery are all under this folder. Compared with ./srcdirectories, there are more static/imagesand static/fontsand views/cgifolders to place image resources, font resources, and ajax request pages respectively. Because these resources do not participate in node tasks, they are directly arranged in the ./distdirectory, saving the cost of copying.
./dist/views/map.html It is the project page map and the project progress completion visualization page, which allows the leader and the project team to see the current progress. The access address (assuming the port number is 2019) is http://localhost:2019/views/map.html. The effect diagram shows:

Some notes:

In the above file directory structure, the ./srcdirectory names and levels of css, js, html, etc. cannot be adjusted, otherwise it will not run. If you make changes, you need to modify the relevant path of run.js synchronously.
css, js and the following subdirectories, currently only support a level 1 folder structure , the name can be any, for example, page1.js, page2.js are for reference purposes, you can delete or change to the name you need.

4. In-depth introduction of "Magic Card"

1. About CSS compilation

Support simple module import and CSS variable compilation, as follows:

@import function

The following two import methods are supported:

@import '../_variable.css';

@import url('../_variable.css');

Only one level of relationship import is supported, and multi-level relationships are not supported. For example, a import b, b import c, when a file is compiled, c will not be nested.

After all, writing static page prototypes does not require too complicated structure.

CSS variables

CSS variables use native CSS syntax, that is, --varname: valuedeclare variables and then var(--varname)use variables. For details, please refer to the article " Understanding CSS/CSS3 Native Variables Var ".

However, there are differences in details, including:

Only support :root{}, html{}, body{}the CSS variable declaration;
Does not support CSS variable nested declaration;

In addition, in order to avoid conflicts with native CSS variables, it is recommended to add !;a distinction in the statement block . This tool will filter this statement during compilation. E.g:

body {!;
    --borderRadius: 2px;
}

other

_CSS files whose file names begin with an underscore will not participate in compilation and merging, and can only be imported by @import.

2. About the merger

Merging only exists in CSS and JS files, and "Magic Card" adopts a folder-based merge strategy.

The specific performance is:

./src/static/jsThe JS in all level 1 folders will be merged into separate files with the same name as the folder. For example, there is a .src/static/js/pagespeace in the folder, page1.jsand page2.jswhen the "Magic Card" runs, it will be ./dist/static/jsmerged into one in the folder pages.js. However, direct exposure to the ./src/static/jsjs file is not involved in the merger, directly copied to ./dist/static/jsthe directory.
Among them, there is an exception, that is lib, the JS under the folder is not involved in the merger, usually used to place JS framework, such as jquery, zepto and the like.
./src/static/cssThe CSS in all level 1 folders below will be merged into separate files with the same name as the folder. For example, .src/static/js/detailsunder the folder, there are home.css, page1.cssand page2.css, as a result, after the "Magic Card" runs, they are all merged into details.cssthe ./dist/static/cssdirectory. Similarly, directly exposed to direct ./src/static/csscss files is not involved in the merger.

Merge does not support multi-level directories, personal experience, very few projects will use more than 2 levels of CSS, JS resources. So it's simple, and the tool level constrains the complexity of the project and makes the structure flatter.

3. About HTML compilation

html file supports module import, using html5 importsyntax, for example:

<link rel="import" href="./include/header.html?nav1=active">

"Magic card" will "./include/header.html"directly import the content of this file, similar to the includefunction in php .

HTML compilation supports easy query

The HTML compilation of "Magic Card" supports passing parameters to imported modules through URL query strings, but the function is relatively simple, that is, replacement, for example:

<link rel="import" href="./include/header.html?nav2=active">

Here nav2=activeit will replace the $nav2$ characters in header.html 'active'.

The original HTML of header.html is:

<h3><a href="./index.html" class="nav-a $nav1$">首页</a></h3>
<h3><a href="./page1.html" class="nav-a $nav2$">页面1</a></h3>
<h3><a href="./page2.html" class="nav-a $nav3$">页面2</a></h3>

After the introduction of the HTML module:

<h3><a href="./index.html" class="nav-a ">首页</a></h3>
<h3><a href="./page1.html" class="nav-a active">页面1</a></h3>
<h3><a href="./page2.html" class="nav-a ">页面2</a></h3>

Therefore, when we click on the navigation to switch to "Page 1", we will find that the navigation buttons are highlighted together, which is nav2=activethe function of the above , as shown below:

Navigation and selection

The replacement rules are as follows:

Replace all $character units that are before and after . If there is a matching query keyword (such as nav2), replace it with the corresponding value (such as active); otherwise, replace it with an empty string ''.

Therefore, although the probability is small, there is still a $$risk of replacing the normal included content in the imported module . If you encounter this problem, you can modify the $characters in run.js to more unusual characters, such as ❤.

Limitations of HTML compilation

At present, "Magic Card" only supports the compilation ./src/views/htmlof .htmlfiles directly exposed in the directory , and subdirectories are .htmldirectly ignored. 95%+ The project is stress-free. If the project is really complicated, with hundreds of prototype pages, you cannot group it by folders. Please refer to the instructions in run.js, do it yourself, and call complie()methods on these folders .

4. About local services

The local service is a simple service written in node.js, which supports the simulation of ajax requests such as get/post, and the loading and display of conventional resources.

For some special format resources, for example .conf, "Magic Card" is not supported, you need to add it to the mimetype object in run.js.

The local service port of "Magic Card" uses the local year:

let port = new Date().getFullYear();

Therefore, the access address starts with http://localhost:2019. There is a problem. Because the year is fixed, the "Magic Card" does not support multiple local services at the same time by default. If you want to open multiple services at the same time This service requires you to modify the port value in run.js.

Five, concluding remarks

There are many static resources for demonstration and testing in the "Magic Card" project by default, including HTML pages and some CSS scaffolding and JS files. In actual development, these resources are mostly useless. You can delete them directly or rename them according to the project content. .

"Magic card" is a very useful small tool for writing HTML static pages, but if your page is a scene with only one or two pages such as operational activities, it is not suitable to use "Magic card". A complete HTML can be straightforward and rude.

In short, if your main job content is to reconstruct HTML pages, the "Magic Card" tool will be very suitable for you.

Welcome to forward, welcome to star, and welcome to fork to build together, for example, to support the compilation of multi-level folders.