Origin.md

   1 # DEPRECATED
   2 This project will no longer be supported as the dependencies have been abandoned.
   3
   4 # LoginManager.js
   5
   6 ## About
   7 #### Easily design your own Linux greeter without having to worry about the implementation.
   8 An event based interface for creating fully customizable Linux login themes
   9 using Lightdm's Webkit2 Greeter.
  10
  11
  12 ![](doc/example.gif)
  13
  14 ## Installation
  15 Install the lightdm and its webkit greeter, make sure that no other version of lightdm is installed on your system.
  16
  17 If your are not already using lightdm, install `lightdm` and `lightdm-webkit2-greeter`.
  18
  19 #### Arch and Manjaro
  20 `# pacman -S lightdm lightdm-webkit2-greeter`
  21 #### Debian (Ubuntu)
  22 `# apt-get install lightdm lightdm-webkit2-greeter`
  23
  24 Now edit the lightdm config, in `/etc/lightdm/lightdm.conf` and set it to use the webkit2 greeter instead.
  25 ```
  26 [Seat:*]
  27 ...
  28 greeter-session=lightdm-webkit2-greeter
  29 ...
  30 ```
  31
  32
  33 Next clone the this repo and copy it to the webkit2 themes folder. (You will need
  34 root permission for the copy)
  35
  36 ```
  37 $ git clone https://github.com/jelenis/login-manager.git
  38 # cp -r lightdm-theme /usr/share/lightdm-webkit/themes/
  39 ```
  40
  41 Lastly, set the value of theme in `/etc/lightdm/lightdm-webkit2-greeter.conf` to lightdm-theme
  42 (or a custom name of your choice set in `index.theme`)
  43 ```
  44 [greeter]
  45 ...
  46 webkit_theme=lightdm-theme
  47 ```
  48
  49 ## Screenshots
  50 ![](doc/example_01.png)
  51
  52 ![](doc/example_04.png)
  53
  54 ## Usage
  55 ### Basic Usage
  56 See [theme.js](js/theme.js) and [theme.css](css/theme.css) for basic usage.
  57
  58 ### API
  59 The [LoginManager](js/LoginManager.js) provides the basic faclities for
  60 authenticating and starting the user session through an asynchronous event based
  61 API. This adds layer of abstraction between UI code and the lightdm interface.
  62
  63 #### LoginManager Interface
  64 Defined in `js/LoginManager.js` as must be included after all Plugins and other dependencies.
  65
  66 _Example: Creating a LoginManager._
  67 ```
  68 // define a singleton LoginManager
  69 let greeter = new LoginManager();
  70 ```
  71 Any code that uses the LoginManager should only be performed after it has
  72 finished initializing itself and all of its plugins. The `ready` event can be
  73 used to so.
  74
  75 _Example: Using LoginManager `ready` event._
  76 ```
  77 // called after greeter and lightdm are initialized
  78 $(greeter).on("ready", function(e) {
  79   // authentication code goes here
  80 });
  81 ```
  82
  83 #### Authetication
  84 A user must be authenticated prior to attempting to login.
  85 `auth(username="", password="", callback)` will asynchronously authenticate,
  86 triggering the appropriate `grant` or `deny` event and passing the resulting
  87 boolean to the callback function.
  88
  89 _Example: Authentcating a user when the enter key is pressed in a password field._
  90 ```
  91 /* Attempt authentication, 'grant' event will be emitted on sucecss
  92 and 'deny' will be emitted on failure */
  93 if (e.keyCode == 13) { // Enter key
  94   let username = $user.children("option:selected").val();
  95   let pass = $password.val();
  96   greeter.auth(username, pass); // no callback specified
  97 }
  98 ```
  99 #### Logging in (starting user session)
 100 Once authentication has been performed you can start a user session with
 101 `login(session_key)`
 102
 103 _Example: listenting for authentication and starting a user session_
 104 ```
 105 // when the user is authenticated, do a transition and login
 106 $(greeter).on("grant", () => {
 107   let session_key = $session.children("option:selected").val();
 108   greeter.login(session_key);
 109 })
 110 .on("deny", () => {
 111   // inform the user that the credentials are invalid
 112   $password.removeClass("valid").addClass("invalid");
 113   $password.val("").prop("placeholder", "Incorrect Password");
 114 });
 115 ```
 116
 117 #### LoginManager Public Definitions
 118 Properties          | Definition                               | Description
 119   ---               |                                          |---
 120   auth              | auth(username="", password="", callback) | Authenticates a user
 121   login             | login(session_key)                       | Starts a user session
 122   shutdown          | shutdown()                               | Poweroff the pc
 123   hibernate         | hibernate()                              | Hibernate the pc
 124   restart           | restart()                                | Restart the pc
 125   users             | get users()                              | Returns array of user objects
 126   sessions          | get sessions()                           | Returns array of sessions objects
 127   fillUserSelect    | fillUserSelect($el)                      | Populates jQuery select element with users
 128   fillSessionSelect | fillSessionSelect($el)                   | Populates jQuery select element with sessions
 129
 130 #### List of Events
 131
 132 Event    | Description
 133 ---      | ---
 134 deny     | Triggered after an unsucessful attempt to authenticate using `auth`
 135 grant    | Triggered after successfuly authenticating using `auth`
 136 init     | Triggered by LoginManager after the 'load' event has been fired by a plugin
 137 load     | Triggered by Plugins after they have finished loading their config files
 138 ready    | Triggered by Plugins and LoginManager after they have finished initailizing
 139 active   | Triggered once by  SplashScreen Plugin after the user interacts with the SplashScreen
 140 inactive | Triggered by the SplashScreen Plugin after a period of inactivity
 141
 142 #### Plugins
 143 Plugins are stored in the LoginManager's `plugin` property and are
 144 dynamically generated by the `plugins` array in
 145 [LoginManager.json](json/LoginManager.json).
 146
 147 _Example: The SplashScreen plugin in LoginManager's config_
 148 ```
 149 "plugins": [
 150   "SplashScreen"
 151 ]
 152 ```
 153 <!--  [SplashScreen](#splash-screen) -->
 154
 155 ##### Example: SplashScreen
 156 The SplashScreen plugin provides facilities to easily add content to a splash
 157 screen without having to worry about the details of implementation. Splash
 158 screen  content can be changed in its config file
 159 [SplashScreen.json](json/SplashScreen.json).
 160
 161 ###### General
 162
 163 The general settings for this plugin are specified in the root of the `.json`
 164 config file. The code will generate the content on this splash
 165 ```
 166 "img": "",             // path to background image (can be left blank for none)
 167 "fit": false,          // fits the background image to screen size, if there is one
 168 "filter": false,       // applies blur to background image
 169 "vignette": true,      // applies dark vignette to background image
 170 "active-timeout": 15,  // specifies the timeout for active/inactive events
 171 "transition": "fade",  // "fade" or "slide" to transition SplashScreen
 172 ```
 173
 174 ###### Content: Clocks
 175 ![splash-screen-sample](doc/splash-screen-sample.png)
 176
 177 The date in the sample image above is created and automatically
 178 updated with the following clock object. You can use custom CSS to style and
 179 position your clock. The `parent-css` property will allow you to add CSS to the
 180 clocks outer `div`.
 181
 182 ```
 183 "content": {
 184   "clock": [{
 185     "format": "dddd, MMMM Do",
 186     "css": {
 187       "color": "white"
 188     },
 189     "parent-css": {
 190       "margin-top": "calc(20vh - 70pt)",
 191       "text-align": "center",
 192       "font-size": "70pt",
 193       "font-family": "Noto Sans",
 194       "font-weight": "lighter",
 195       "text-shadow": "rgba(0, 0, 0, 0.5) 0px 7px 10px",
 196     }
 197     ...
 198 ```
 199
 200 To add the sytlized time to our splash screen we need to add another clock. This
 201 one will consist of two parts one for the actual time and another for the sylized
 202 AM/PM. This means formats, and thus two css objects.
 203
 204 ```
 205 "content": {
 206   "clock": [{
 207     ...
 208 },{
 209   "format": ["h:mm", "A"], // two formats for two clocks on the same line
 210   "css": [
 211     {"font-size": "65pt", "font-weight": 200 },
 212     {"font-size": "30pt", "font-weight": "lighter", "margin-left": "10pt"}
 213   ],
 214   "parent-css": {
 215     "margin-top": "20vh",
 216     "color": "white",
 217     "font-family": "Noto Sans",
 218     "text-align": "center",
 219     "text-shadow": "rgba(0, 0, 0, 0.5) 0px 7px 10px",
 220   }
 221 }],
 222 ```
 223
 224 ###### Content: html
 225 Provides an interface to add any custom content to the SplashScreen.
 226
 227 _Example: adding welcome text to SplashScreen, see default theme for an image._
 228 ```
 229 content: {
 230   "html": [{
 231     "html":"<text style='display: none' class='active-appear'>Press any key to login</text>",
 232     "css": {
 233       "margin-top": "5vh",
 234       "font-weight": "200",
 235       "font-size": "23pt",
 236       "text-align": "center",
 237       "color": "rgba(255, 255, 255, 0.8)"
 238     }
 239   }]
 240 }
 241 ```