design
The best place to start! Before you submit anything to the public git repo it will be checked with this design guidelines. After confirm that your code comply with the rules (and is working!) the code will be merged.
##Basics
The app is based on Polymer and web components architecture. Meaning: everything is an HTMLElement. Or at least is extending it. It's not a regular MVC architecture but - in a way - it is. There are elements that behaves as controllers controlling logic of part of the application, there are elements (models) that only purpose is to handle database and data and finally there are elements that only serves as views.
There is one more type of elements - utils elements - which supports some functionality or view but are not directly related to the application. For example <arc-ctrl-*> is a crutial part of the app. However <file-drop> element is has been developed to support some functionality in the app but is rather helper element that can be moved to any other project or to be published on https://customelements.io.
To distinguish elements purpose there is an naming system for components.
For consistency and to distinguish elements purpose follow the following names style.
All elements names must follow HTML naming style which means using "-" (dash) as a word break. The same is for element attributes but this is required by the Polymer design guidelines.
All app specific elements starts with arc prefix. It means that it will be used for all controllers, models and views (if they are app specific views).
Controller is the biggest part of the apps architecture. Each separate part of the app that have enclosed logic and supports part of the app functionality is a component. You can think of component as a single page application in the ARC. For example Settings or Request is an component. However, import data table or the response view is not a component. Even it this elements have enclosed some kind of logic but it is view logic and not app logic (like performing app specific operations). In this scenario controller elements should keep designed elements flow and data exchange (even if it is only a two-way data binding between model and view). But still it is a role of the controller.
Components will be run when the app's URL change and the routing system will recognize the first part of the path as a component name. Actually it's more complicated but it will be enough for now.
All controllers names should be following format:
<arc-[CONTROLER-NAME]-controller></arc-[CONTROLER-NAME]-controller>Where [CONTROLER-NAME] is a lower case controller name that use "-" as a word separator.
####Example
<arc-request-controller></arc-request-controller>Models should provide a data for components directly from the storage they support. Models can use external libraries however they are responsible for providing and updating data in the store.
All models names should be following format:
<arc-[MODEL-NAME]-model></arc-[MODEL-NAME]-ctrl>Where [MODEL-NAME] is a lower case model's object name that use "-" as a word separator.
####Example
<arc-request-object-model></arc-request-object-model>Views are an UI elements for controller. In this context view names should be related to the component name.
It the view represents an UI element or some UI logic not directly related to the app functionality the it should not follow this rule. For example <file-drop> element is a part of the app but it's not directly related to the app itself, it could be replaced with any other element supporting similar feature and it could be used in any other project. This kind of elements should follow regular HTML naming rules.
All models names should be following format:
<arc-[VIEW-NAME]-view></arc-[VIEW-NAME]-view>Where [VIEW-NAME] is a lower case view's name that use "-" as a word separator.
####Example
<arc-request-view></arc-request-view>Utils are every other elements that has been developed for the ARC but are not either controller, model or view. Names of this elements may start with the arc prefix but it's not required. It have arc prefix if the element is application specific element and would not be used in different projects.
<file-drop></file-drop>
<arc-loader-screen></arc-loader-screen>Because all elements will be executed in the strict CSP environment there will be most probably at least two files for each component: a .html file that is imported vie HTML import and external .js file that supports logic (or behavior in case of views).
|- component-folder/
| - assets/
| - asset.png
| - component.html
| - component.js
| - other.js
| - changelog.md
Element folder may contain any number of other resources that are used in the app. Elements however can't use external resources (outside of the app structure). So the elements should have all the resources they need.
First of all follow the Google JavaScript Style Guide. Secondly use gulp lint command before you submit any code to the repository. Linter configuration is available in gulpfile.js file in the lint task.
See the Google HTML/CSS style guide for CSS and HTML rules.
In both cases you can skip the part with compatibility with other browsers. It must work in Chrome.
I suggest following editor configuration.
The .editorconfig file:
root = true
[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = trueThe .jscsrc file:
{
"preset": "google",
"disallowSpacesInAnonymousFunctionExpression": null,
"disallowTrailingWhitespace": null,
"maximumLineLength": 100,
"excludeFiles": ["node_modules/**"]
}The .jshintrc file:
{
"esnext": true,
"node": true,
"browser": true,
"bitwise": true,
"camelcase": false,
"curly": true,
"eqeqeq": true,
"immed": true,
"indent": 2,
"latedef": true,
"noarg": true,
"quotmark": "single",
"undef": true,
"unused": true,
"newcap": false,
"globals": {
"wrap": true,
"unwrap": true,
"Polymer": true,
"Platform": true,
"page": true,
"app": true,
"chrome": true
}
}