diff --git a/docs/AspNetCore/Bundling-Minification.md b/docs/AspNetCore/Bundling-Minification.md new file mode 100644 index 0000000000..7f2d9bb88e --- /dev/null +++ b/docs/AspNetCore/Bundling-Minification.md @@ -0,0 +1,3 @@ +## ASP.NET Core MVC Bundling & Minification + +TODO \ No newline at end of file diff --git a/docs/AspNetCore/Client-Side-Package-Management.md b/docs/AspNetCore/Client-Side-Package-Management.md new file mode 100644 index 0000000000..edf002dcc0 --- /dev/null +++ b/docs/AspNetCore/Client-Side-Package-Management.md @@ -0,0 +1,114 @@ +## ASP.NET Core MVC Client Side Package Management + +ABP framework can work any type of client side package management system. Even you can decide to use nothing and manually manage your dependencies. + +However, ABP framework best works with **NPM/Yarn**. It provides tools to make it easier to work with and built-in modules are configured to work with NPM/Yarn by default. + +Finally, we suggest the [**Yarn**](https://yarnpkg.com/) over the NPM since it's faster, more stable and also compatible with the NPM. + +### @ABP NPM Packages + +ABP is a modular platform. Every developer can create modules and the modules should work together in a **compatible** and **stable** state. + +One challenge problem is **versions of the depended NPM packages**. What if two different module use the same JavaScript library but its different (and potentially incompatible) versions. + +To solve the versioning problem, we created a **standard set of packages** those depends on some common third-party libraries. Some example packages are [@abp/jquery](https://www.npmjs.com/package/@abp/jquery), [@abp/bootstrap](https://www.npmjs.com/package/@abp/bootstrap) and [@abp/font-awesome](https://www.npmjs.com/package/@abp/font-awesome). You can see the **list of packages** from the [Github repository](https://github.com/volosoft/abp/tree/master/npm/packs). + +The benefit of a **standard package** is: + +* It depends on a **standard version** of a package. Depending on this package is **safe** because all modules depend on the same version. +* It contains the gulp task to copy library resources (js, css, img... files) from the **node_modules** folder to **wwwroot/libs** folder. See the *Mapping The Library Resources* section for more. + +Depending on a standard package is easy. Just add it to your **package.json** file as you normally add a package. + +````json +{ + ... + "dependencies": { + "@abp/bootstrap": "^0.3.1" + } +} +```` + +It's suggested to depend on a standard package instead of directly depending on a third-party package. + +#### Package Installation + +After depending on a npm package, all you should do is to run the yarn command from the command line to install the packages: + +```` +yarn +```` + +You can instead use the `npm install` but the [Yarn](https://yarnpkg.com/) is suggested as mentioned before. + +#### Package Contribution + +If you need a third-party NPM package that is not in the standard set of packages, you can create a Pull Request on the Github repository. A pull requests that follows these rules are accepted: + +* Package name should be named as `@abp/package-name` for a `package-name` on NPM (example: `@abp/bootstrap` for the `bootstrap` package). +* It should be the **latest stable** version of the package. +* It should only depend a **single** third-party package. It can depend on multiple `@abp/*` packages. +* The package should include a `abp.resourcemapping.js` file formatted as defined in the *Mapping The Library Resources* section. This file should only map resources for the depended package. + +See current standard packages for examples. + +### Mapping The Library Resources + +Using NPM packages and NPM/Yarn tool is the de facto standard for client side libraries. NPM/Yarn tool creates a **node_modules** folder in the root folder of your web project. + +Next challenge is to copying needed resources (js, css, img...) files from the node_modules into a folder inside the **wwwroot** folder to make it accessible to the clients/browsers. + +ABP defines Gulp based tasks to **copy resources** from **node_modules** to **wwwroot/libs** folder. Each **standard package** (see the *@ABP NPM Packages* section) defines the mapping for its own files. So, most of times, you only configure dependencies. + +The **startup templates** are already configured to work all these out of the box. This section will explain the configuration options. + +#### Resource Mapping Definition File + +An application defines a JavaScript file named `abp.resourcemapping.js` which is formatted as in the example below: + +````js +module.exports = { + imports: [ + "./node_modules/@abp/bootstrap/abp.resourcemapping.js" + ], + aliases: { + "@node_modules": "./node_modules", + "@libs": "./wwwroot/libs" + }, + clean: [ + "@libs" + ], + mappings: { + + } +} +```` + +* **imports** section defines the dependencies of the application. This example depends on the @abp/bootstrap standard package and it knows how to copy bootstrap resources (js, css... files) into the wwwroot/libs/bootstrap folder. +* **aliases** section defines standard aliases (placeholders) those can be used in the mapping paths. **@node_modules** and **@libs** are required (by the standard packages), you can define your own aliases to reduce duplication. +* **clean** section is a list of folders to clean before copying the files. +* **mappings** section is a list of mappings of files/folders to copy. This example does not copy any resource itself, but depends on a standard package. + +An example mapping configuration is shown below: + +````js +mappings: { + "@node_modules/bootstrap/dist/css/bootstrap.css": "@libs/bootstrap/css/", + "@node_modules/bootstrap/dist/js/bootstrap.bundle.js": "@libs/bootstrap/js/" +} +```` + +#### Using The Gulp + +Once you properly configure the `abp.resourcemapping.js` file, you can run the gulp command from the command line: + +```` +gulp +```` + +When you run the gulp, all related packages will copy their own resources into the **wwwroot/libs** folder. Running yarn & gulp again is only necessary if you make a change in your dependencies in the **package.json** file. + +#### See Also + +* [Bundling & Minification](Bundling-Minification.md) \ No newline at end of file diff --git a/docs/Index.md b/docs/Index.md index b332479d45..e39b8872e6 100644 --- a/docs/Index.md +++ b/docs/Index.md @@ -48,8 +48,10 @@ * ASP.NET Core MVC * API Versioning * User Interface - * Themes + * [Client Side Package Management](AspNetCore/Client-Side-Package-Management.md) + * [Bundling & Minification](AspNetCore/Bundling-Minification.md) * Tag Helpers + * Themes * Data Access * [Entity Framework Core Integration](Entity-Framework-Core.md) * [MongoDB Integration](MongoDB.md) diff --git a/docs/Object-To-Object-Mapping.md b/docs/Object-To-Object-Mapping.md index b0d80246f7..9bb22e0c66 100644 --- a/docs/Object-To-Object-Mapping.md +++ b/docs/Object-To-Object-Mapping.md @@ -1,3 +1,3 @@ -## Data Transfer Objects +## Object To Object Mapping TODO \ No newline at end of file