README.md

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