11 |
13 | {{error}}
14 |
15 |
13 | {{error}}
14 |
15 |
11 |
25 |
27 | 
3 | 4 | With MEAN framework, you can create members, articles, or add more features with packages from the 5 | community. 6 |
7 |Browse our packages
58 |
mean help can also be used in conjunction with any command to get more information about that particular functionality. For example, try mean help init to see the options for init
175 | ```bash
176 | $ mean help [command]
177 | ```
178 | ### Users
179 |
180 | Information can be display for a specific customer via mean user email. Email is required. User roles can be assigned or removed with the --addRole (or -a) and --removeRole (or -r) options, respectively.
For example, the admin role is required to edit tokens.
182 | 183 | ```bash 184 | $ mean userAll of the remaining of the commands must be run from the root folder of your MEAN application.
192 |Contributed MEAN packages can be installed or uninstalled via the CLI. Also, currently installed modules can be viewed with the list command.
Mean packages installed via the installer are found in /node_modules
201 | #### Search 202 | To find new packages run the *mean search* command 203 | ```bash 204 | $ mean search [packagename] 205 | ``` 206 | `mean search` will return all of the available packages, `mean search [packagename]` will filter the search results. 207 | 208 | #### Scaffolding 209 | To create a new MEAN app, runmean init. Name for the application is optional. If no name is provided, "mean" is used. The MEAN project will be cloned from GitHub into a directory of the application name.
210 | ```bash
211 | $ mean init [name]
212 | $ cd [name] && npm install
213 | ```
214 | Note: git must be installed for this command to work properly.
215 | 216 | ### Misc 217 |Check the database connection for a particular environment (e.g. development (default), test, production) and make sure that the meanio command line version is up to date.
219 | ```bash 220 | $ mean status 221 | ``` 222 |A simple shortcut to open the mean documentation in your default browser.
224 | ```bash 225 | $ mean docs 226 | ``` 227 | 228 | ## Packages 229 | 230 | Everything in mean.io is a package and when extending mean with custom functionality make sure you create your own package and do not alter the core packages. 231 | 232 | The mean.io package system allows developers to create modular code that provides useful tools that other mean developers can use. The packages, when published, are plug-and-play and are used in a way very similar to traditional npm packages. 233 | 234 | The mean.io package system integrates all the packages into the mean project as if the code was part of mean itself and provides the developers with all the necessary tools required to integrate their package into the host project. 235 | 236 | There are two types of packages: 237 | 238 | **Custom Packages** are generated by the mean scaffolder and contain most of your application logic. Custom packages are found in */packages/custom* and can be published as a contrib package for use by other developers. 239 | 240 | **Contrib Packages** are installed by the mean installer and are found at */packages/contrib*. Contrib packages are "plug and play". 241 | 242 | ### Core Packages 243 | 244 | All `Core` packages can be overridden by other packages allowing you to extend and adapt it to fit your specific needs. See `Overriding views` for detailed examples. 245 | 246 | 247 | #### System 248 | The "system" package creates the basic pages as well as defines the layout of the site and integrates the menu into the page. The system package also allows us to define things such as rendering engines, static files and routing on the client and server side. 249 | #### Users 250 | The "users" package creates the database model of the user, provides validation as well as various login and registration features. 251 | #### Access 252 | The "access" package manages permissions and middleware. It controls the various authentication methods and is dependent on the users package 253 | #### Theme 254 | The "theme" package adds some basic CSS and other assets such as images and backgrounds 255 | #### Articles 256 | The "articles" package is typically used as an example starting point for managing content that might be used in a blog or cms. The full CRUD is implemented on the server and client. 257 | ### File structure 258 | The file structure is similar to that of the mean project itself 259 | 260 | `Fundamental` Files at the `root` of the package 261 | 262 | **Server** 263 | 264 | Packages are registered in the **app.js** 265 | Defines package name, version and `mean=true` in the **package.json** 266 | 267 | All of the Server side code resides in the `/server` directory. 268 | 269 | Server 270 | --- config # Configuration files 271 | --- controllers # Server side logic goes here 272 | --- models # Database Schema Models 273 | --- routes # Rest api endpoints for routing 274 | --- views # Swig based html rendering 275 | 276 | **Client** 277 | 278 | All of the Client side code resides in the `/public` directory. 279 | 280 | public 281 | --- assets # JavaScript/CSS/Images (not aggregated) 282 | --- controllers # Angular controllers 283 | --- config # Contains routing files 284 | --- services # Angular services (also directive and filter folders) 285 | --- views # Angular views 286 | 287 | All JavaScript within `public` is automatically aggregated with the exception of files in `public/assets`, which can be manually added using the `aggregateAsset()` function. 288 | 289 | Files within the `public` directory of the package can be accessed externally at `/[package-name]/path-to-file-relative-to-public`. For example, to access the `Tokens` Angular controller, `tokens/controllers/tokens.js`. 290 | 291 | ###Registering a Package 292 | 293 | In order for a Package to work it needs to be registered. By doing this you make the package system aware that you are ready and that other packages are able to depend on you. The packages are registered from within `app.js`. 294 | 295 | When registering you are required to declare all your dependencies in order for the package system to make them available to your package. 296 | 297 | ```javascript 298 | // Example of registering the MyPackage 299 | MyPackage.register(function(app, auth, database) { 300 | // ... 301 | }); 302 | ``` 303 | 304 | MEAN has 3 pre registered dependencies: 305 | - `app` Makes the express app available . 306 | - `auth` Includes some basic authentication functions 307 | - `database` Contains the Mongoose database connection 308 | 309 | > All dependencies specified must be registered in order to use them 310 | 311 | ###Dependency Injection 312 | 313 | > An injection is the passing of a dependency (a service) to a dependent 314 | > object (a client). The service is made part of the client's state. 315 | > Passing the service to the client, rather than allowing a client to 316 | > build or find the service, is the fundamental requirement of the 317 | > pattern. [Wikipedia](https://en.wikipedia.org/wiki/Dependency_injection) 318 | 319 | 320 | Dependency injection allows you to declare what dependencies you require and rely on the package system to resolve all dependencies for you. Any package registered is automatically made available to anyone who would like to depend on them. 321 | 322 | Looking again at the registration example we can see that `MyPackage` depends on the `Tokens` package and can make use of its full functionality, including overriding it. 323 | 324 | ```javascript 325 | // Example of registering the tokens package 326 | MyPackage.register(function(app, auth, database, Tokens) { 327 | 328 | // I can make use of the tokens within my module 329 | MyPackage.someExampleFunction('some parameter'); 330 | 331 | // I can override functions 332 | MyPackage.someExampleFunction = function(param) { 333 | //my custom logic goes here 334 | }; 335 | }); 336 | ``` 337 | 338 | > Packages when in code are used in a capitalized form 339 | 340 | ###Angular Modules and Dependencies 341 | 342 | Every package registration automatically creates a corresponding angular module of the form `mean.[package-name]` 343 | 344 | The package system injects this information into the mean init functions and allows developers to base their controllers, services, filters, directives etc on either an existing module or on their own one. 345 | 346 | In addition you are able to declare which angular dependencies you want your angular module to use. 347 | 348 | Below is an example of adding an angular dependency to our angular module. 349 | 350 | ```javascript 351 | // Example of adding an angular dependency of the ngDragDrop to the 352 | MyPackage.angularDependencies(['ngDragDrop']); 353 | ``` 354 | 355 | > See the assets section for an example how to add external libraries to 356 | > the client such as the `gDragDrop `javascript library 357 | 358 | ###Assets and Aggregation 359 | 360 | All assets such as images, javascript libraries and CSS stylesheets should be within `public/assets` of the package file structure. 361 | 362 | Javascript and CSS from `assets` can be aggregated to the global aggregation files. By default all javascript is automatically wrapped within an anonymous function unless given the option `{global:true}` to not enclose the javascript within a contained scope 363 | 364 | ```javascript 365 | 366 | //Adding jquery to the mean project 367 | MyPackage.aggregateAsset('js','jquery.min.js'); 368 | 369 | //Adding another library - global by default is false 370 | MyPackage.aggregateAsset('js','jquery.min.js', {global:true}); 371 | 372 | //Adding some css to the mean project 373 | MyPackage.aggregateAsset('css','default.css'); 374 | ``` 375 | 376 | > Javascript files outside of assets are automatically aggregated and 377 | > injected into the mean project. As a result libraries that you do not 378 | > want aggregated should be placed within `public/assets/js` 379 | 380 | The aggregation supports the ability to control the location of where to inject the aggregated code and if you add a weight and a group to your aggregateAsset method you can make sure it's included in the correct region. 381 | 382 | ```javascript 383 | MyPackage.aggregateAsset('js','first.js',{global:true, weight: -4, group: 'header'}); 384 | ``` 385 | 386 | >The line that gets loaded in your head.html calls the header group and injects the js you want to include first- 387 | > in packages/system/server/views/includes/head.html 388 | > 389 | 390 | ###Settings Object 391 | The settings object is a persistence object that is stored in the packages collection and allows for saving persistent information per package such as configuration options or admin settings for the package. 392 | 393 | Receives two arguments the first being the settings object the second is a callback function 394 | 395 | ```javascript 396 | MyPackage.settings({'someSetting':'some value'}, function (err, settings) { 397 | // You will receive the settings object on success 398 | }); 399 | 400 | // Another save settings example this time with no callback 401 | // This writes over the last settings. 402 | MyPackage.settings({'anotherSettings':'some value'}); 403 | 404 | // Get settings. Retrieves latest saved settings 405 | MyPackage.settings(function (err, settings) { 406 | // You now have the settings object 407 | }); 408 | ``` 409 | 410 | > Each time you save settings you overwrite your previous value. 411 | > Settings are designed to be used to store basic configuration options 412 | > and should not be used as a large data store 413 | 414 | 415 | ###Express Routes 416 | All routing to server side controllers is handled by express routes. The package system uses the typical express approach. The package system has a route function that passes along the package object to the main routing file typically `server/routes/myPackage.js` 417 | 418 | By default the Package Object is passed to the routes along with the other arguments 419 | `MyPackage.routes(app, auth, database);` 420 | 421 | 422 | Example from the `server/routes/myPackage.js` 423 | 424 | ```javascript 425 | // The Package is past automatically as first parameter 426 | module.exports = function(MyPackage, app, auth, database) { 427 | 428 | // example route 429 | app.get('/myPackage/example/anyone', function (req,res,next) { 430 | res.send('Anyone can access this'); 431 | }); 432 | }; 433 | ``` 434 | 435 | ###Angular Routes 436 | The angular routes are defined in `public/routes/myPackage.js`. Just like the latest version of mean, the packages use the `$stateProvider` 437 | 438 | ```javascript 439 | $stateProvider 440 | .state('myPackage example page', { 441 | url: '/myPackage/example', 442 | templateUrl: 'myPackage/views/index.html' 443 | }); 444 | ``` 445 | 446 | > The angular views are publically accessible via templateUrl when 447 | > prefixed with the package name 448 | 449 | ###Menu System 450 | 451 | Packages are able to hook into an existing menu system and add links to various menus integrated within Mean. 452 | 453 | Each link specifies its `title`, `template`, `menu` and `role` that is allowed to see the link. If the menu specified does not exist, a new menu will be created. The menu object is made accessible within the client by means of a *menu angular service* that queries the menu controller for information about links. 454 | 455 | Below is an example how to add a link to the main menu from `app.js` 456 | 457 | ```javascript 458 | //We are adding a link to the main menu for all authenticated users 459 | MyPackage.menus.add({ 460 | title: "myPackage example page", 461 | link: "myPackage example page", 462 | roles: ["authenticated"], 463 | menu: "main" 464 | }); 465 | ``` 466 | 467 | 468 | > You can look at the angular header controller in the mean project for 469 | > more info. You can find it `public/system/controllers/header.js` and 470 | > see how the menu service is implemented 471 | 472 | ###Html View Rendering 473 | The packages come built in with a rendering function allowing packages to render static html. The default templating engine is *swig*. The views are found in `server/views` of the package and should end with the `.html` suffix 474 | 475 | Below is an example rendering some simple html 476 | 477 | ```javascript 478 | app.get('/myPackage/example/render', function (req,res,next) { 479 | MyPackage.render('index', {packageName:'myPackage'}, function (err, html) { 480 | //Rendering a view from the Package server/views 481 | res.send(html); 482 | }); 483 | }); 484 | ``` 485 | 486 | ###Overriding the default layouts 487 | One is able to override the default layout of the application through a custom package. 488 | 489 | Below is an example overriding the default layout of system and instead using the layouts found locally within the package 490 | 491 | ```javascript 492 | MyPackage.register(function(system, app) { 493 | app.set('views', __dirname + '/server/views'); 494 | // ... 495 | ``` 496 | 497 | > Please note that the package must depend on `System` to ensure it is 498 | > evaluated after `System` and can thus override the views folder 499 | 500 | ### Overriding views 501 | You may override public views used by certain core packages. To create a custom home page, you would create a custom package and modify the script in it's public folder like so: 502 | 503 | ```javascript 504 | angular.module('mean.mycustompackage', ['mean.system']) 505 | .config(['$viewPathProvider', function($viewPathProvider) { 506 | $viewPathProvider.override('system/views/index.html', 'mycustompackage/views/myhomepage.html'); 507 | }]); 508 | ``` 509 | 510 | This will render *mycustompackage/views/myhomepage.html* as the home page. 511 | 512 | ### Creating your own package 513 | To create your own package and scaffold its initial code, run the following command: 514 | 515 | ```bash 516 | $ mean package