Commit 4a84a585 authored by Aaron Harder's avatar Aaron Harder

Tweaks to docs

parent acc6c229
Pipeline #715 skipped
......@@ -12,7 +12,8 @@ Below are the basic steps to get a new Blacklight instance up and running in you
- If you haven't already, install the [Blacklight cli tool](https://gitlab.entropy.cc/blacklight/blacklight-cli) with the following command:
```bash
> npm install -g git+https://gitlab.entropy.cc/blacklight/blacklight-cli.git
> npm install -g blacklight-cli
> bl --help ## To confirm successful install
```
- Add the `blcd` helper command to your `.bash_profile` or `.bashrc` file.<br>_Note:_ This step is optional, but recommended because the `blcd` command can greatly expedite navigation of Blacklight's directory structure from a command shell.
......@@ -27,17 +28,17 @@ blcd(){
## Download and Start Sling
Apache Sling comes as a standalone JAR file. You can download the latest version of the Apache Sling JAR file via your web browser from the [Sling homepage](https://sling.apache.org/) (look for _"Downloads"_ in the left-hand nav bar).
Apache Sling comes as a standalone **.jar** file. You can download the latest version of the Apache Sling **.jar** file via your web browser from the [Sling homepage](https://sling.apache.org/) (look for _"Downloads"_ in the left-hand nav bar).
Alternately, you can download the Sling version 8 JAR file from the command line:
Alternately, you can download the Sling version 8 **.jar** file from the command line:
```bash
> mkdir /opt/sling ## Or some other folder, if you prefer
> cd /opt/sling
> cd ~ ## Or some other folder, if you prefer
> mkdir sling && cd sling
> wget http://apache.mirrors.pair.com/sling/org.apache.sling.launchpad-8.jar
```
Once the **.jar** file is downloaded, run the jar file with the following command:
Once the **.jar** file is downloaded, run it with the following command:
```bash
> java -Xmx512M -jar org.apache.sling.launchpad-8.jar -p 4500 & ## Assumes Sling version 8
......@@ -51,10 +52,11 @@ http://127.0.0.1:4500/
Create a new, empty Blacklight website by running the following command. Answer the prompts as outlined below.
```bash
> cd ~ ## Or some other folder, if you prefer
> bl init my-site
```
- **Git URL** -- can be use any Git URL you like, including the fake sample URL, `git@gitlab.mycompany.com:my-site/`
- **Git URL** -- can be any Git URL you like, including the fake sample URL, `git@gitlab.mycompany.com:my-site/`
- **Sling url** -- The Sling instance you initiated above is running at http://127.0.0.1:4500
- **Sling username** -- Is `admin` and **password** is also `admin`.
- **Website domain name** -- Is not important for this test installation of Blacklight. Put in any domain you like.
......
......@@ -160,7 +160,7 @@ Here is a description of the three types of `requestPreprocessor` directives tha
While this optional step is very similar to the much more prominent **model processor** stage of the render pipeline, the `slingPreprocess` step has the ability to add and alter `resourceTypes` to the base JSON retrieved for any page, something which Blacklight's main model processor is currently unable to do. In future, Blacklight's internals may be tweaked to allow `resourceType` manipulation in the main model processor, but until then `slingPreprocess` is the best way to do so.
# Blacklight Code Organization
# Blacklight Code Organization & IDE Usage
![Blacklight Code Organization](/alt/blacklight/docs/images/blacklight-code-organization.svg "Blacklight Code Organization")
......@@ -174,26 +174,25 @@ The Blacklight module loader looks for four key folders in each site module:
4. `docs` -- Documentation files relevant to this module, in Markdown format.
### Soft-linked Module Folders & IDE Usage
## Soft-linked Module Folders & IDE Usage
![img:class=right fancy|data-clearfix=7](/alt/blacklight/docs/images/blacklight-module-soft-linking.svg "Module Soft Linking")
![img:class=right fancy|data-clearfix=8](/alt/blacklight/docs/images/blacklight-module-soft-linking.svg "Module Soft Linking")
One quirk of Blacklight folder layout is that, upon installation, three of the four folder types listed above are soft-link "mounted" into a second location in the top-level folder hierarchy. The diagram at the right illustrates where these secondary soft links reside.
This soft-linking accelerates and simplifies file lookup when Blacklight is running. For example, all module `public` folders get mapped into a contiguous set of module-specific folders under a top-level `public` umbrella folder, with a resulting structure that translates directly to a logical URL namespace. `components` and `apps` also benefit from this remapping, for similar reasons.
Although this soft-linking makes things easier for the Blacklight server, for developers it can ambiguate how best to approach the files when doing development. When using a folder-oriented IDE such as [Sublime Text](https://www.sublimetext.com/) or [Atom](https://atom.io/), the question becomes which folder to start with, and which folders to hide. Two primary options are worth considering when working in a folder-based IDE:
Although this soft-linking makes things easier for the Blacklight server, for developers it can ambiguate how best to approach the files when doing development. When using a folder-oriented IDE such as [Sublime Text](https://www.sublimetext.com/) or [Atom](https://atom.io/), the question becomes which folder to **open** in the IDE window, and then which folders to **hide**. Two primary options are worth considering when working in a folder-based IDE:
1. **All files and modules in a single window** -- Looking at the example on the right, you'd open the "my-site" folder, and then work your way down the file tree to find the particular file you need. For example, to open the main template for the landing page component in the "my-area" site module, you'd drill down to: `/my-site/components/my-site/area-one/pages/landing/landing.hbs`. When taking this view on the files in your IDE, you will probably want to **hide** the `blacklight_modules` folder, so as not to get duplicate results when searching in files, etc.
1. **All files and modules in a single window** -- For this option, looking at the example on the right, you'd open the entire "my-site" folder in your IDE window, and then use the IDE's left-nav file tree to work your way down to the particular file you need. For example, to edit the main template for the landing page component in the "my-area" site module, you'd drill down to: `/my-site/components/my-site/area-one/pages/landing/landing.hbs`. When taking this view on the files in your IDE, you will probably want to **hide** the `blacklight_modules` folder, so as not to get duplicate results when searching in files, etc.
2. **Each module in a different window** -- Again, using the example in the right-hand figure, and to edit the same file as in option 1, open the module folder in your IDE: `/my-site/blacklight_modules/my-site/area-one`. Then navigate in the IDE's file tree to `components/pages/landing/landing.hbs`.
2. **Each module in a different window** -- Again, using the example in the right-hand figure, and to edit the same file as in option 1, you'd first open _only_ the relevant module folder in your IDE window: `/my-site/blacklight_modules/my-site/area-one`. Then from there, navigate in the IDE's left-nav file tree to your file: `components/pages/landing/landing.hbs`.
Option 2 has a few notable advantages over option 1: Notice the path to the example file in the tree is much shorter in option 2 than in option 1, and also there is no need to hide any folders in your IDE to get optimal search results. Option 2 gives you a concise view of all `component`, `public`, and `apps` files, with much less confusing distance between them, and no files from unrelated modules cluttering the view. So depending on how you like to conceptualize things, option 2 is mostly upside as compared to option 1. One of the only potential downsides for option 2 is that you need to jump between IDE windows when you wish to work on another module; though arguably, that is actually an advantage too.
Option 2 has a few notable advantages over option 1: Notice the path to the example file in the tree is much shorter in option 2 than in option 1, which means less "drilling down" to get where you need. Also with option 2, there is no need to hide any folders in your IDE to get optimal search results (though just like with option 1, you may still wish to hide `node_modules` and any `public/**/vendor` folders). Another advantage of option 2 is it gives you a concise view of all `component`, `public`, and `apps` files, with much less confusing distance between them, and no files from unrelated modules cluttering the view.
Option 1 allows you to see three key files that are not visible from option 2: the main `index.js`, `config/default.json` and `config/local.json`. Option 1 also provides an easy way to search through **all** modules for certain stings or references from a single point. So even if, like the creators of Blacklight, you prefer using option 2 for most module-specific development, it is definitely useful to keep option 1 handy for certain types of changes.
Diagram: Blacklight Render, Blacklight Edit, Model Processor pipeline
So depending on how you like to conceptualize things, option 2 is mostly upside as compared to option 1. One of the only potential downsides you might find for option 2 is the need to jump between IDE project windows when you wish to work on another module; though arguably, even that has some advantages in terms of mental compartmentalization of concerns. For Sublime Text, the [GotoWindow](https://packagecontrol.io/packages/GotoWindow) package provides a very nice keyboard shortcut for quickly jumping between multiple project windows, using **super** + **shift** + **o**.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment